documentation: add a full table of content for API pages

[MrLixm]

Hello,

This a improvement request for the OpenColorIO documentation.

issue

When browsing the API documentation, example https://opencolorio.readthedocs.io/en/latest/api/config.html it is very hard to find the object you are looking for because of the lack of a table of contents providing a summarized overview of the whole page. We can also notice that all the code objects are missing a permalink anchor to quickly share a direct link to them.

If we have a look at the pages like https://opencolorio.readthedocs.io/en/latest/guides/authoring/authoring.html we can see in the left side-bar that there is some table-of-content going on but it is shallow, i.e. only listing top-level headings and not lower-lever headings like h3.

^ screenshot of the doc showing that h2 are not being listed in the sidebar toc

request

I would really love:

• adding a deep table-of-content (showing all headings level) in an easy to access area in the page (I personally love to that are pinned to the right of your screen and stay in position when you scroll)
• adding permalink for every code object that is being documented

---

Let me know if something is not clear. Best, Liam.

[czerouni]

Reading the documentation about the documentation, I am not sure how doable this is, but I will give it a shot as a Dev Days thing.

[carolalynn]

Amazing @czerouni, we'll be here to support you! Feel free to say hello in our #devdays channel on the OCIO slack.

[czerouni]

So as I suspected, I have good news and bad news. The bad news is that I couldn't find a way to do what is specifically requested, which is to expand the categories down the left side, with links.

But the good news is that you can already do something like this, by clicking on either of the API labels, either on the left nav or on the top menu. See the two attached images. And the methods listed in the center of the page are active links to the API.

Top menu bar:

[MrLixm]

Thanks for the tip, I was not aware of this index page ! That's helpful. However it is still a very big list to browse through.

For my initial request I don't see as mandatory to add more granularity in the existing left navigation bar. Just adding a table of content that show all heading levels, at the top of the active page would be great (in the same way that the API page does but just with the content of the sub-section you selected).

[czerouni]

Do you mean - you click on "Config" on the left nav, and what you get in the main pane is this:

Followed by the tabs for Python and C++?

Just trying to understand the goal.

[MrLixm]

yes that would work, in the main pane or anywhere else, but to have a quick access to those information.