Skip to content

Latest commit

 

History

History
168 lines (123 loc) · 6.22 KB

toctree.rst

File metadata and controls

168 lines (123 loc) · 6.22 KB
Raw
topic

Table of Contents Tree

triple: Sphinx; Syntax; Table of Contents Tree

Table of Contents Tree

Now would be a good time to introduce the .. toctree::. One of the main concepts in is that it allows multiple pages to be combined into a cohesive hierarchy. Since does not have facilities to interconnect several documents, or split documents into multiple output files, uses a custom directive to add relations between the single files the documentation is made of, as well as tables of contents.

The .. toctree:: directive is the central element and a fundamental part of this structure. Consider this example:

The above directive example will output a TOC (Table of Contents) in the page where it occurs, using the individual TOCs (including "sub-TOC trees") of the files given in the directive body. The :maxdepth: 2 argument tells to include 2 levels of headers in it's output. It will output the 2 top-level headers of the pages listed; by default, all levels are included. This also tells that the other pages are sub-pages of the current page, creating a "tree" structure of the pages.

This accomplishes two things:

  • Tables of contents from all those files are inserted, with a maximum depth of argument :maxdepth:, that means one nested heading. .. toctree:: directives in those files are also taken into account.
  • knows that the relative order of the files install, support and so forth, and it knows that they are children of the shown file, the library index. From this information it generates "next chapter", "previous chapter" and "parent chapter" links.

In the end, all files included in the build process must occur in (only) one .. toctree:: directive; will emit a warning if it finds a file that is not included, because that means that this file will not be reachable through standard navigation.

The special file index.rst at the root of the source directory is the "root" of the TOC tree hierarchy; from it the "Contents" page is generated.

Note

The TOC Tree is also used for generating the navigation elements inside . It is quite important, and one of the most powerful concepts in .

Sidebar navigation menu

The index.rst file serves as a front-page to the documentation and contains the main tables of content, defined using .. toctree:: directives. These .. toctree:: directives control the sidebar navigation menu. To add a new document to a table of content, add the file name (without the .rst extension) to the relevant list of file names in index.rst or any other (but only one) "sub-TOC trees".

Secondary sub-TOC trees

Collections of documents are mostly given their own table of content on an individual page (see, for example: ../appendix and ../glossary). In these cases, the page containing the .. toctree:: serves as a sort of intro page for the collection. That intro must, itself, be included in the concepts/toctree:Sidebar navigation menu. The contents of a .. toctree:: appear as section links in another .. toctree:: it is included in. That is, if a .. toctree:: in index.rst lists .. glossary::, and glossary.rst has a .. toctree::, then the contents of that second .. toctree:: will appear in the concepts/toctree:Sidebar navigation menu, as sub-items to ../glossary.

Indeed, this is precisely the case in this document currently.

How this document uses main and secondary TOC

  • Major topics get a .. toctree:: in index.rst

    Major topics include things like:

    • Each major parts (../extensions, ../themes, )
    • Large, general categories like Releases, Contributing, or Building

    Major topic tables of content include both sub-collection intro pages and also individual pages that don't fit into a sub-collection.

    The :caption: attribute of the .. toctree:: directive may but not must defines the section label in the concepts/toctree:Sidebar navigation menu.

  • Within a large topic, documents are grouped into collections of related pages, defined by a .. toctree:: on a topic intro page.

    Intro pages (pages that contain secondary .. toctree:: directives) may include additional content, introducing the collection or providing contextual way-finding. However, this is not always necessary or desirable. Use your judgment, and avoid stating things just for the sake of having some text. ("Here are the pages in this collection.")

    We also (very occasionally) include .. toctree:: directives in sub-collection pages, such as:

    • ../extensions/bibtex,
    • ../extensions/spelling,
    • ../themes/rtd,

Tip

If it not obvious where a new document should appear in the navigation, the best practice is to simply ask about it in the GitHub issue driving the new page.

Note

For way-finding purposes, we sometimes create an concepts/lists:Unordered (bullet) lists of page links rather than a .. toctree:: directive (for example, see index.rst). We do this when using a .. toctree:: would create redundant links in the concepts/toctree:Sidebar navigation menu.

\clearpage\phantomsection