sphinx / doc / concepts.rst

Full commit

Sphinx concepts

Document names

Since the reST source files can have different extensions (some people like .txt, some like .rst -- the extension can be configured with :confval:`source_suffix`) and different OSes have different path separators, Sphinx abstracts them: all "document names" are relative to the :term:`source directory`, the extension is stripped, and path separators are converted to slashes. All values, parameters and suchlike referring to "documents" expect such a document name.

Examples for document names are index, library/zipfile, or reference/datamodel/types. Note that there is no leading slash.

The TOC tree

Since reST does not have facilities to interconnect several documents, or split documents into multiple output files, Sphinx 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.

Special names

Sphinx reserves some document names for its own use; you should not try to create documents with these names -- it will cause problems.

The special document names (and pages generated for them) are:

  • genindex, modindex, search

    These are used for the general index, the module index, and the search page, respectively.

    The general index is populated with entries from modules, all index-generating :ref:`description units <desc-units>`, and from :dir:`index` directives.

    The module index contains one entry per :dir:`module` directive.

    The search page contains a form that uses the generated JSON search index and JavaScript to full-text search the generated documents for search words; it should work on every major browser that supports modern JavaScript.

  • every name beginning with _

    Though only few such names are currently used by Sphinx, you should not create documents or document-containing directories with such names. (Using _ as a prefix for a custom template directory is fine.)


[1]The maxdepth option does not apply to the LaTeX writer, where the whole table of contents will always be presented at the begin of the document, and its depth is controlled by the tocdepth counter, which you can reset in your :confval:`latex_preamble` config value using e.g. \setcounter{tocdepth}{2}.
[2]A note on available globbing syntax: you can use the standard shell constructs *, ?, [...] and [!...] with the feature that these all don't match slashes. A double star ** can be used to match any sequence of characters including slashes.