sphinxcontrib-fulltoc – Include a full table of contents in your sidebar.¶

sphinxcontrib-fulltoc is an extension for the Sphinx documentation system that changes the HTML output to include a more detailed table of contents in the sidebar. By default Sphinx only shows the local headers for the current page. With the extension installed, all of the page titles are included, and the local headers for the current page are also included in the appropriate place within the document.

Installing¶

Basic Installation¶

Install the package along with Sphinx.

There are two ways to install the extension. Using pip:
```
$ pip install sphinxcontrib-fulltoc
```
or from the source tree:
```
$ python setup.py install
```
Add the extension to the list in your conf.py settings file for each project where you want to use it:
```
# conf.py
...
extensions = ['sphinxcontrib.fulltoc']
...
```
Rebuild all of the HTML output for your project.

Advanced Use¶

If you have customized the theme for your documentation, and especially if you have modified the way sidebars are applied, you may need to take some additional configuration steps.

localtoc.html¶

The localtoc.html template is used to insert the table of contents in the sidebar of an HTML page. By default it looks like:

{%- if display_toc %}
  <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
  {{ toc }}
{%- endif %}

sphinxcontrib-fulltoc forces display_toc to be set to True and replaces the toc variable with the full table of contents. If your localtoc.html document has been changed, you may need to update it to include {{ toc }}, or restore the template to the default.

The Full Full TOC¶

If you do not want the table of contents collapsed to ignore subheadings on other pages, you can replace the {{ toc }} line in localtoc.html with a call to toctree(), which accepts two parameters.

toctree(collapse=True)¶

Generate a table of contents relative to the current document.

Parameters:	collapse (bool) – Controls whether or not remote parts of the tree are shown. Setting to True only shows internal links on the current page. Setting to False shows internal links on all pages.
Returns:	HTML text of the table of contents

For Developers¶

If you would like to contribute to sphinxcontrib-fulltoc, these instructions should help you get started. Patches, bug reports, and feature requests are all welcome through the GitHub site. Contributions in the form of patches or pull requests are easier to integrate and will receive priority attention.

Building Documentation¶

The documentation for sphinxcontrib-fulltoc is written in reStructuredText and converted to HTML using Sphinx, as you might expect. The build itself is driven by setuptools. You will need the following packages in order to build the docs:

Sphinx
docutils
sphinxcontrib-fulltoc

Once all of the tools are installed into a virtualenv using pip, run python setup.py build_sphinx to generate the HTML version of the documentation:

$ python setup.py build_sphinx

The output version of the documentation ends up in ./build/sphinx/html inside your sandbox.

History¶

1.0

First public release

0.1

Internal version