1. Sphinx#
1.1. Configuration#
Add to your conf.py
:
extensions = ["sphinx_external_toc"]
external_toc_path = "_toc.yml" # optional, default: _toc.yml
external_toc_exclude_missing = False # optional, default: False
Note the external_toc_path
is always read as a Unix path, and can either be specified relative to the source directory (recommended) or as an absolute path.
1.2. Basic Structure#
A minimal ToC defines the top level root
key, for a single root document file:
root: intro
The value of the root
key will be a path to a file, in Unix format (folders split by /
), relative to the source directory, and can be with or without the file extension.
Note
This root file will be set as the master_doc
.
Document files can then have a subtrees
key - denoting a list of individual toctrees for that document - and in-turn each subtree should have a entries
key - denoting a list of children links, that are one of:
file
: path to a single document file in Unix format, with or without the file extension (as forroot
)glob
: path to one or more document files via Unix shell-style wildcards (similar tofnmatch
, but single stars don’t match slashes.)url
: path for an external URL (starting e.g.http
orhttps
)
Important
Each document file can only occur once in the ToC!
This can proceed recursively to any depth.
root: intro
subtrees:
- entries:
- file: doc1
subtrees:
- entries:
- file: doc2
subtrees:
- entries:
- file: doc3
- url: https://example.com
- glob: subfolder/other*
This is equivalent to having a single toctree
directive in intro
, containing doc1
,
and a single toctree
directive in doc1
, with the :glob:
flag and containing doc2
, https://example.com
and subfolder/other*
.
As a shorthand, the entries
key can be at the same level as the file
, which denotes a document with a single subtree.
For example, this file is exactly equivalent to the one above:
root: intro
entries:
- file: doc1
entries:
- file: doc2
entries:
- file: doc3
- url: https://example.com
- glob: subfolder/other*
1.3. File and URL titles#
By default, the initial header within a file
document will be used as its title in generated Table of Contents.
With the title
key you can set an alternative title for a document. and also for url
:
root: intro
subtrees:
- entries:
- file: doc1
title: Document 1 Title
- url: https://example.com
title: Example URL Title
1.4. ToC tree options#
Each subtree can be configured with a number of options (see also sphinx toctree
options):
caption
(string): A title for the whole the subtree, e.g. shown above the subtree in ToCshidden
(boolean): Whether to show the ToC within (inline of) the document (defaultFalse
). By default it is appended to the end of the document, but see also thetableofcontents
directive for positioning of the ToC.maxdepth
(integer): A maximum nesting depth to use when showing the ToC within the document (default -1, meaning infinite).numbered
(boolean or integer): Automatically add numbers to all documents within a subtree (defaultFalse
). If set toTrue
, all sub-trees will also be numbered based on nesting (e.g. with1.1
or1.1.1
), or if set to an integer then the numbering will only be applied to that depth.reversed
(boolean): IfTrue
then the entries in the subtree will be listed in reverse order (defaultFalse
). This can be useful when usingglob
entries.titlesonly
(boolean): IfTrue
then only the first heading in the document will be shown in the ToC, not other headings of the same level (defaultFalse
).
These options can be set at the level of the subtree:
root: intro
subtrees:
- caption: Subtree Caption
hidden: False
maxdepth: 1
numbered: True
reversed: False
titlesonly: True
entries:
- file: doc1
subtrees:
- titlesonly: True
entries:
- file: doc2
or, if you are using the shorthand for a single subtree, set options under an options
key:
root: intro
options:
caption: Subtree Caption
hidden: False
maxdepth: 1
numbered: True
reversed: False
titlesonly: True
entries:
- file: doc1
options:
titlesonly: True
entries:
- file: doc2
You can also use the top-level defaults
key, to set default options for all subtrees:
root: intro
defaults:
titlesonly: True
options:
caption: Subtree Caption
hidden: False
maxdepth: 1
numbered: True
reversed: False
entries:
- file: doc1
entries:
- file: doc2
Warning
numbered
should not generally be used as a default, since numbering cannot be changed by nested subtrees, and sphinx will log a warning.
Note
By default, title numbering restarts for each subtree. If you want want this numbering to be continuous, check-out the sphinx-multitoc-numbering extension.
1.5. Using different key-mappings#
For certain use-cases, it is helpful to map the subtrees
/entries
keys to mirror e.g. an output LaTeX structure.
The format
key can be used to provide such mappings (and also initial defaults).
Currently available:
jb-article
:Maps
entries
->sections
Sets the default of
titlesonly
totrue
jb-book
:Maps the top-level
subtrees
toparts
Maps the top-level
entries
tochapters
Maps other levels of
entries
tosections
Sets the default of
titlesonly
totrue
For example:
defaults:
titlesonly: true
root: index
subtrees:
- entries:
- file: doc1
entries:
- file: doc2
is equivalent to:
format: jb-book
root: index
parts:
- chapters:
- file: doc1
sections:
- file: doc2
Important
These change in key names do not change the output site-map structure.
1.6. Excluding files not in ToC#
By default, Sphinx will build all document files, regardless of whether they are specified in the Table of Contents, if they:
Have a file extension relating to a loaded parser (e.g.
.rst
or.md
)Do not match a pattern in
exclude_patterns
To automatically add any document files that do not match a file
or glob
in the ToC to the exclude_patterns
list, add to your conf.py
:
external_toc_exclude_missing = True
Note that, for performance, files that are in hidden folders (e.g. in .tox
or .venv
) will not be added to exclude_patterns
even if they are not specified in the ToC.
You should exclude these folders explicitly.
Important
This feature is not currently compatible with orphan files.