Documentation needs updates across the board

[studyreserve]

Issue was originally titled [documentation] chip_integration.md. Original content follows.

---

Greetings.

OpenLane/docs/source/chip_integration.md documentation file in the master branch includes broken links in "Hardening The Full Chip" chapter:

1. "You could take this full chip as an example."
2. "First you need to harden the padframe as a separate macro, check this flow as an example on how to do so."
3. "if it's presented in a chip_io module, otherwise you can harden it separately as indicated in this flow." 4,5) "Here is an example. Or a hardened chip_io.gds and chip_io.lef following this."
4. "The interactive script for the IOs does the following:"
5. "Given these inputs the following interactive script script. Mainly, it does the following steps:"
6. "Run DRC and LVS checks here."
7. "Otherwise, refer to this for more details about the syntax."

It seems, that caravel project "mpw-one-b" no longer exists, there is "mpw-one" project only, should it leads there?

The last broken link leads to non existing PDN.md file. I could not figure out where it was supposed to lead.

[donn]

Sadly, this is a more general situation than any one file- OpenLane's documentation is in general need of a concerted update effort.

Some of our team members are doing some work on that, but frankly we're currently swamped with Caravel work. So community input would be sincerely appreciated: including entirely different strategies to handle documentation, if applicable. It's the current biggest sore spot with the flow, unfortunately.

@maliberty What strategy do you use for documenting OpenROAD?

[maliberty]

@donn are you asking technically (e.g. markdown, sphinx) or more process (probably no better than yours)?

[donn]

Both, frankly. You have relatively good documentation for the Tcl APIs.

[maliberty]

@donn We write our documentation with markdown. @vvbandeira can comment on how we process that to produce the readthedocs.

TCL commands are pretty straight forward in that when something changes the PR should include a doc update. Code review is the main enforcement tool, though it still relies on a human check rather than anything automated. The place where we have more trouble is with high level descriptive documentation as that doesn't belong to any single change/owner.

[mithro]

BTW - You should use Sphinx

@umacor can also provide advice as he has been working on improving the F4PGA documentation (and hopefully soon the SkyWater PDK documentation too).

[vvbandeira]

@vvbandeira can comment on how we process that to produce the readthedocs.

There's nothing fancy here. Just a simple setup and webhook triggered on commits to the master branch to generate the final HTML. A quick look at OL conf.py and .readthedocs.yml suggests we are using a very similar approach.

[donn]

@proppy's suggesting the following:

Prompt

The following page often gets out of date w/ the change to the default TCL configs as shown in #1087: https://github.com/The-OpenROAD-Project/OpenLane/blob/master/configuration/README.md https://github.com/The-OpenROAD-Project/OpenLane/blob/master/regression_results/datapoint_definitions.md

Proposal

It would be nice to find a way to autogenerate those, maybe some of the options listed in https://wiki.tcl-lang.org/page/Source+Documentation+Tools could be explored?