On the read the docs page, I found it a bit awkward that I can not explicitly provide a URL for a User Guide for reference. Same for developer’s guide.
There are links for subsections (for example UI https://slicer.readthedocs.io/en/latest/user_guide/user_interface.html), and of course the top level page (https://slicer.readthedocs.io/en/latest/index.html) but not for User Guide itself.
Yes, that is odd. I guess something about readthedocs, but I don’t know if there’s a workaround (nothing obvious to me anyway).
Readthedocs shows documents. It cannot render a folder. If you add “User manual” and “Developer manual” pages (some kind of overview or introduction) then that can referred to.
You can experiment with making any changes and submit a pull request. Automatic tests of the pull request include full documentation generation, so you can check everything before the changes are merged.
I’ve tried to create distinct links to the “User manual” and “Developer manual”. Readthedocs does not show multiple levels of the documentation in the navigation tree, unless the user manually opens a section (this could be probably changed by customizing the theme, but then we would need to keep maintaining it, so I would avoid that).
Therefore, creating user and developer subsections would make the navigation bar a bit less usable (it would only show two items, so users would always need to click to open a section before seeing more content). See preview here: https://slicer--5280.org.readthedocs.build/en/5280/
Another option would be to keep “user guide” pages in a top-level section and just move the “developer guide” one level lower (essentially, we would have “Slicer documentation” and “Developer guide” section). See preview here: https://slicer--5279.org.readthedocs.build/en/5279/
@muratmaga @pieper @jcfr What do you think? Which one do you like better?
My vote is for number 2.
I could live with either, but I also prefer the second one because it gives you more options so you are more likely to get what you need in fewer clicks.