docs/contents: use captions in the global toc

[umarcor]

Fix for f4pga/sphinx_f4pga_theme#11

[mithro]

I'm a little bit confused why there are so many files being deleted?

[umarcor]

I'm a little bit confused why there are so many files being deleted?

In the current "main" there is one file for each "chapter" which includes a toctree only with a caption. For instance: https://github.com/google/skywater-pdk/blob/main/docs/analog.rst. In those cases, the caption is "useless" because it's not shown in the sidebar. In this PR, I move all of those "second level toctrees" into the index.rst. As a result, the captions are properly processed (and shown).

On the other hand, there are several files which contain a single title starting with TODO. I changed all of those to a .. todo:: directive, which is more idiomatic in the context of Sphinx.

Last, a few files did have more than one top-level heading. In those cases, I split the content to have one top-level heading per file.

[mithro]

Random comment -- Should the "Foundry provided" libraries (https://skywater-pdk--366.org.readthedocs.build/en/366/contents/libraries/foundry-provided.html) and IO cells (https://skywater-pdk--366.org.readthedocs.build/en/366/contents/libraries/sky130_fd_io/README.html) appear in the "PDK Contents" section on the left?

[proppy]

@umarcor thanks for working on this, this really improve the navigation experience a lot!

One potential concerns, wouldn't removing the standalone rst files in favor of "including them" break some existing links to those pages?

Ex:
https://skywater-pdk.readthedocs.io/en/main/rules/hv.html
Becomes nested under:
https://skywater-pdk--366.org.readthedocs.build/en/366/rules/methodologies/index.html
Thus rendering the previous url 404.

It also seems that we loose some granulary in the left nav (in favor of moving the element as section in the right nav), and I just want to make sure that's a conscious choice (as it does affect the discoverability of those elements).