Skip to content

Conversation

@minijackson
Copy link
Contributor

Fixes #3160.

This switches the documentation from the "default" theme to the "Read the Docs" theme, which provides a sidebar that is consistent across all pages, which makes it easier to navigate, and easier to grasp the structure of the documentation.

There are other Sphinx themes, which you can see here: https://sphinx-themes.org/
but the RTD theme is very popular, and well designed, in my opinion.

@minijackson
Copy link
Contributor Author

If you're interested, you can enable building PRs in the Read the Docs configuration, which would give you a preview documentation website on each PR.

I think it's in https://app.readthedocs.org/projects/control-system-studio/, under "Settings", "Build pull requests for this project"

@minijackson
Copy link
Contributor Author

Note: not in the sphinx-themes.org directory, but there's also the Shibuya theme that looks really good.

@jacomago
Copy link
Contributor

@shroffk @tynanford Can you give more of us access to the readthedocs project.

@shroffk
Copy link
Member

shroffk commented Apr 23, 2025

I have enabled the build on PR

the "Read the Docs" Sphinx theme provides a sidebar
that is consistent across all pages,
which makes it easier to navigate.
this makes it so that the caption is shown on the sidebar,
and clearly separate the user and dev documentation
@minijackson
Copy link
Contributor Author

minijackson commented Apr 24, 2025

I had to do a git push to trigger the RTD build.

I've also used the :caption: toctree argument, so that it's shown on the sidebar, and removed the appendix from the index, because it didn't contain anything.

@jacomago
Copy link
Contributor

Looks way better to me

@shroffk
Copy link
Member

shroffk commented Apr 24, 2025

I agree... like mentioned in the issue ticket this will bring back the missing index.
@jacomago @minijackson can I merge this or are there other changes too?

@minijackson
Copy link
Contributor Author

@shroffk I personally think merging as-is should be fine

@shroffk shroffk merged commit 20dd0cc into ControlSystemStudio:master Apr 24, 2025
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation pointing to /latest/, but /stable/ documentation seems better

3 participants