VTR flow library documentation is just a skeleton -- should fill in

[vaughnbetz]

https://docs.verilogtorouting.org/en/latest/vtr/python_libs/vtr/ has the skeleton of documentation for this library, but only the headings are there.

Proposed Behaviour

Complete the documentation

Context

Our flow scripts are pretty complex (and useful) so documenting them is helpful. We do have pretty reasonable documentation on the overall scripts, so if you conclude no documentation is needed on the library you could instead delete this documentation tab. But I suspect documentation here will be useful.

[github-actions]

This issue has been inactive for a year and has been marked as stale. It will be closed in 15 days if it continues to be stale. If you believe this is still an issue, please add a comment.

[vaughnbetz]

@jgoeders : we should close this one out. We still have just a skeleton of documentation for the VTR flow library. If you or a delegate can fill it out some that would be best.

[jgoeders]

@WhiteNinjaZ Could you work on documenting this?

[WhiteNinjaZ]

Yea I can fill this in

[WhiteNinjaZ]

It looks like the documentation has been added already, at least when I build the docs locally, I get the generated docstrings for each of the functions. It looks like the web doc is still blank though. @vaughnbetz it is my understanding that the web docs are automatically updated with each PR?

[vaughnbetz]

The CI automatically updates the docs. Not sure why they don't show up then ... I'm guessing there is something wrong with the doxyfile that says which ones to show on the web. See https://docs.verilogtorouting.org/en/latest/dev/code_documentation/
Possibly it is different for python ... our documentation on doxyfiles seems to be C++ focused. If you determine we should update the developer guide doxyfile section go ahead and do that too.

[vaughnbetz]

In case what I wrote is confusing: to make the web docs we need to do two things:

• Actually write the comments in Doxygen format in the source files
• Modify the doxyfiles (.rst files) as specified in https://docs.verilogtorouting.org/en/latest/dev/code_documentation/#validation-of-doxygen-comments-updating-api-reference
• CI will build the docs, and clicking on the documentation link in the CI tests is simpler than building locally, so that's what I usually do.

[WhiteNinjaZ]

@jgoeders