sphinx-tagtoctree

Sphinx table-of-contents with super powers


License
MIT
Install
pip install sphinx-tagtoctree==0.9.3

Documentation

Sphinx Extension: TagTocTree

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.

How it works

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

Usage

The documentation assumes you have a Sphinx project running.

  • Install using PIP:

    pip install sphinx-tagtoctree
  • In your Sphinx configuration file (conf.py), add a entry for tagtoctree:

    extensions = [
        'sphinx_tagtoctree'
    ]
  • (Optional) Add configuration value for tagtoctree_tag. If none is provided, the default tagtoctree will be used.

    tagtoctree_tag = 'tagtoctree'
  • 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
    
      **