This is an extension to the documentation engine Sphinx. It allows you to include pages in a table of contents by using tags assigned to a page.
This extension adds a new directive tagtoctree
, which creates a tree-like
table-of-contents, filtering pages by a tag filter.
Directive | Configuration | Produces |
---|---|---|
toctree (*) |
![]() |
![]() |
tagtoctree |
![]() |
![]() |
(*) Sphinx native toctree
The documentation assumes you have a Sphinx project running.
-
Install using PIP:
pip install sphinx-tagtoctree
-
In your Sphinx configuration file (
conf.py
), add an entry fortagtoctree
:extensions = [ 'sphinx_tagtoctree' ]
Configurations that can be added to conf.py
:
tagtoctree_tag
-
(Optional) Add a configuration value for
tagtoctree_tag
. If none is provided, the defaulttagtoctree
will be used. This is the tag you will add to your pages.tagtoctree_tag = 'tagtoctree'
tagtoctree_allowed_in_token
-
(Optional) Add a configuration value for
tagtoctree_allowed_in_token
with a string
of specials characters that should be allowed in tags. If none is provided, the default.:_
will be used.tagtoctree_allowed_in_token = '.:_-'
-
For each page, add a header on the top with the values of your tags. See examples page1 and page2 in this repo.
-
Finally, add a
tagtoctree
directive where you want your table-of-contents to be displayed. Example:.. tagtoctree:: :maxdepth: 1 :glob: :caption: Pages with tag "Product" :tag: Product **
## Usage - boolean filter
You can specify a more complex filter using boolean expressions.
Examples of valid expressions are:
* ``(Customer AND Product)`` Include pages with tags Customer and Product.
* ``(Customer OR Product) AND NOT(Sales)`` Include pages that have tags Customer or Product, but which do not have tag Sales. Equivalent to ``(Customer OR Product) AND ~ Sales``
* ``(NOT Customer) AND NOT(Sales)`` Include pages that do have neither Customer nor Product.
Examples:
```rst
.. tagtoctree::
:maxdepth: 1
:glob:
:caption: Pages filtered with an expression: (Customer AND Product)
:tag_expr: Customer AND Product
**
.. tagtoctree::
:maxdepth: 1
:glob:
:caption: Pages filtered with an expression: (Customer OR Product) AND Sales
:tag_expr: (Customer OR Product) AND Sales
**
.. tagtoctree::
:maxdepth: 1
:glob:
:caption: Pages filtered with an expression: (Customer OR Product) AND NOT Sales
:tag_expr: (Customer OR Product) AND NOT Sales
**
.. tagtoctree::
:maxdepth: 1
:glob:
:caption: Pages filtered with an expression: (NOT Customer) AND NOT(Sales)
:tag_expr: (NOT Customer) AND NOT(Sales)
**