DOCSEARCHbyAlgolia
Submit Docs

Read the Docs Sphinx Theme

repository·master·Indexed 26 days ago

https://github.com/readthedocs/sphinx_rtd_theme

A theme for Sphinx documentation projects designed for an optimized reading experience on desktop and mobile devices. Version 3.1.0 provides extensive customization via html_theme_options for navigation, TOC depth, and appearance, and supports structured API documentation for Python, C++, and JavaScript.

Tokens
5.1K
Snippets
20
Records
34
Agent score
89%

What's inside sphinx_rtd_theme

  1. Use the Read the Docs Sphinx Theme

    master
    The sphinx_rtd_theme is a Sphinx theme designed for an optimized reader experience on both desktop and mobile devices. While it is the standard theme used by projects hosted on Read the Docs, it can be integrated into any Sphinx-based documentation project.

  2. Use sticky_navigation for long menus

    master
    The sticky_navigation setting controls the behavior of the sidebar menu when it contains many items. When enabled, it allows the menu and the main content area to scroll appropriately, ensuring that long navigation structures remain accessible without obscuring the page content.

  3. Test theme changes with tox

    master

    To ensure compatibility across different Sphinx and Python versions, use tox.

    Running a specific environment: tox -e py312-sphinx74

    Viewing built documentation: After a successful build, the HTML files are located in the directory specified by the Sphinx output (e.g., .tox/py312-sphinx74/tmp/html).

    Comparing builds: To spot UI issues, build multiple environments and compare them in a browser:

    1. Build environment A: tox -e py312-sphinx62
    2. Build environment B: tox -e py312-sphinx74
    3. Open both: firefox .tox/py312-sphinx62/tmp/html/index.html and firefox .tox/py312-sphinx74/tmp/html/index.html

    Testing against a specific git tag: To compare a feature branch against a stable tag (e.g., 0.5.2), use the -qa postfix to prevent overwriting files:

    % git checkout 0.5.2
% tox -e py310-sphinx53-qa
% git checkout feature/example-pull-request
% tox -e py310-sphinx53
    % tox -e py312-sphinx74

  6. Document C++ APIs

    master

    Use Sphinx C++ domain directives to document C++ types, functions, classes, members, variables, and enums. This allows the sphinx_rtd_theme to render structured C++ API documentation.

    .. cpp:type:: MyType
   Some type

.. cpp:function:: const MyType Foo(const MyType bar)
   Some function type thing

.. cpp:class:: template<typename T, std::size_t N> std::array
   Some cpp class

.. cpp:member:: float Sphinx::version
   The description of Sphinx::version.

.. cpp:var:: int version
   The description of version.

.. cpp:enum:: MyEnum
   An unscoped enum.
   .. cpp:enumerator:: A

.. cpp:enum-class:: MyScopedEnum
   A scoped enum.
   .. cpp:enumerator:: B

  7. Render Math equations in Sphinx RTD Theme

    master

    You can render mathematical equations using inline :math: roles or block-level .. math:: directives. To reference a specific equation, use the :eq: role with the label assigned in the math block.

    Inline Math: :math:X_{0:5} = (X_0, X_1, X_2, X_3, X_4)`

    Block Math with Labels: Use the :label: option within the math directive to create a referenceable anchor.

    Referencing Equations: Use :eq: followed by the label name.

  8. Upgrade sphinx_rtd_theme

    master

    To upgrade the theme, ensure sphinx_rtd_theme is included in your project's dependencies; pip install will then fetch the latest compatible version.

    If you need to test a pre-release version, you must specify the exact version string (e.g., sphinx-rtd-theme==1.1.0b3), as pip ignores pre-releases by default.

    Best Practice: It is recommended to pin the version of Sphinx used in your project. sphinx_rtd_theme releases are marked for compatibility with specific Sphinx versions, so if you do not pin the theme itself, you will receive the latest compatible release.

  9. Develop using Dockerized environment

    master

    If you have Docker available, you can isolate the build environment and avoid local dependency conflicts. The image is tagged as sphinx_rtd_theme:latest.

    1. Build the Docker image: docker-compose build
    2. Run the development webserver: docker-compose run sphinx_rtd_theme dev
    3. Quickly build new CSS/JS assets: make docker-build-all

    Note: If you change Node or Python requirements, you must rebuild the image using docker-compose run sphinx_rtd_theme build. If you change SASS or JS, you must rebuild the assets.

    $ docker-compose build
$ docker-compose run sphinx_rtd_theme dev
$ make docker-build-all

  11. Document JavaScript APIs

    master

    Use Sphinx JavaScript domain directives to document modules, classes, and methods. This enables structured documentation for JavaScript libraries within the theme.

    .. js:module:: module_a.submodule

.. js:class:: ModTopLevel

.. js:method:: ModTopLevel.mod_child_1

.. js:method:: ModTopLevel.mod_child_2

  12. Avoid direct installation from GitHub

    master

    Direct installation of sphinx_rtd_theme via GitHub is deprecated because compiled assets (CSS/JS) are being removed from the source repository to ease maintenance. These assets will only be included in the built packages available on PyPI.

    Users should install the theme via PyPI instead of installing directly from the GitHub source repository.