Read the Docs Theme

Примечание

This feature only applies to Sphinx documentation. We are working to bring it to our other documentation backends.

By default, Read the Docs will use its own custom sphinx theme unless you set one yourself in your conf.py file. Likewise, setting the theme to default will accomplish the same behavior. The theme can be found on github here and is meant to work independently of Read the Docs itself if you want to just use the theme locally.

This blog post provides some info about the design, but in short, the theme aims to solve the limitations of Sphinx’s default navigation setup, where only a small portion of your docs were accessible in the sidebar. Our theme is also meant to work well on mobile and tablet devices.

Contributing to the theme

If you have issues or feedback, please open an issue on the theme’s GitHub repository which itself is a submodule within the larger RTD codebase. That means any changes to the theme or the Read the Docs badge styling should be made there. The code is separate so that it can be used independent of Read the Docs as a regular Sphinx theme.

How the Table of Contents builds

Currently the left menu will build based upon any toctree(s) defined in your index.rst file. It outputs 2 levels of depth, which should give your visitors a high level of access to your docs. If no toctrees are set in your index.rst file the theme reverts to sphinx’s usual local toctree which is based upon the heading set on your current page.

It’s important to note that if you don’t follow the same styling for your rST headers across your documents, the toctree will misbuild, and the resulting menu might not show the correct depth when it renders.

Other style notes

• As a responsive style, you should not set a height and width to your images.
• Wide tables will add a horizontal scroll bar to maintain the responsive layout.