Organizing content in a Rubin user guide#
Once your Sphinx project is configured to use the Rubin user guide theme, the next step is to organize your content into pages and directories, and create links into those pages with Sphinx toctrees.
The HTML theme of Rubin user guides, based on PyData Sphinx Theme, offers multiple layers of navigational UI.
Taking best advantage of that navigational UI requires specific considerations for how the Sphinx
toctree directives are structured.
This page describes the navigational architecture of the HTML theme and its relationship to Sphinx toctrees, and includes suggested layouts for common project types.
Sections are the root level
toctree items in the homepage of your documentation project (the root-level
In this example, there are three sections (a user guide, a developer guide, and a change log):
.. toctree:: user-guide/index api dev/index changelog
You use separate
toctree directives to organize the homepage.
Sections are still created from each root entry.
This example is functionally equivalent to the first example, above:
.. toctree:: user-guide/index .. toctree:: api .. toctree:: dev/index .. toctree:: :hidden: changelog
Creating sections without adding content to the index page#
By default Sphinx
toctree directives create content on the page.
Sometimes, you don’t want that content on the homepage.
You can create a section in the header navigation without creating a visible link on the homepage by using the
hidden option on the
This technique is commonly used for adding the change log as a section in software documentation.
Using a hidden
toctree referencing a single page allows you to put the change log in the correct slot on the header navigation without creating an awkward entry on the homepage:
.. toctree:: :hidden: changelog
The names of sections are based on the titles (top-level heading) of the pages linked from the toctree on the homepage.
In the following example, the name of the section is
.. toctree:: api
########## Python API ########## Page content...
To avoid overcrowding the navigation bar, these section names need to be kept very short (one to two words).
Sections are listed horizontally in the top navigation (for the desktop navigation experience), which limits the number of sections that can be displayed. Making the section navigation useful requires you to carefully plan both the number of sections, and the lengths of those section.
As a guideline, expect to use 1 – 5 sections. Therefore, your sections should be fairly broad, and shouldn’t need to grow in number as the project grows. For example, a common sectioning pattern for open source Python projects is:
These sections are oriented around content type and audience. The sections are designed so that users can easily see all user-oriented documentation, and documentation for contributors is purposefully sequestered to avoid audience confusion. Since the API reference and change log documentation are common topics, those are also available as sections. Further, any new content could fall into one of these sections, making this a future-proof organization.
A different strategy is to organize sections around features. This works well if there are a small number of distinct features, and those features are orthogonal from each other. For example, the Documenteer documentation has sections for supporting Rubin’s distinct documentation configurations (user guides, technical notes, and Science Pipelines / EUPS stack documentation), along with a section for the Sphinx extensions, the change log, and a developer’s guide. This is a potentially risky architecture, because new feature categories could break the navigational design. However, it creates a clean and bespoke documentation experience when pulled off well.
The theme provides an escape valve for overcrowded navigation bars by collecting excess sections into a “More” drop-down. This drop down can be used to collect little-used sections, or more internally-oriented sections such as development documentation. You can set the number of sections that appear in the navigation bar before the “More” button with the sphinx.theme.header_links_before_dropdown configuration.
These are suggested section layouts for common types of Rubin Observatory documentation projects. Larger user guides often require bespoke design.
User guide ========== .. toctree:: user-guide/index Python API ========== .. toctree:: api .. toctree:: :hidden: changelog Developer guide =============== .. toctree:: dev/index