search

SoundScapeRenderer / ssr

Main source code repository for the SoundScape Renderer
http://spatialaudio.net/ssr/
GNU General Public License v3.0
134 stars 53 forks source link

Manual: hide TOC by default on index page, add usage instructions #327

Closed mgeier closed 1 year ago

mgeier commented 1 year ago

I thought that the full TOC on the first page might be a bit overwhelming?

And I'm not sure if it helps to give some usage instructions ...

mgeier commented 1 year ago

Rendered: https://ssr--327.org.readthedocs.build/en/327/

JensAhrens commented 1 year ago

I like the idea, but seeing all layers of sections in the TOC is indeed a lot. It is possible to hide subsections? Never mind if not.

mgeier commented 1 year ago

It is possible to hide subsections?

This is what I originally tried, and yes, it's possible with the :maxdepth: option (see https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree).

However, this also removed the deeper levels from the sidebar, but I would like to have all levels available there.

Then I tried removing the main TOC completely (with the :hidden: option), but I think sometimes it might be useful to see the full TOC, so I didn't really like that.

Another option I explored was using a separate HTML page that only contains the TOC, like Sphinx itself does it: https://www.sphinx-doc.org/en/master/contents.html I think this isn't too bad, but then I had the idea of initially hiding the TOC on the main page but providing a way to show it on demand. So far, I think this is the best option of everything I tried, but maybe there are more things to try?

Anyway, we can merge this PR now and keep improving on the situation if and when we have further ideas?