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:`documentation root`, the extension is stripped, and path separators are converted to slashes. All values, parameters and suchlike referring to "documents" expect such a document name.

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.