.. toctree:: +¶

Enhanced Sphinx TocTree which shows classes, functions etc. as if they were sections.

Docs
Tests
PyPI
Anaconda
Activity
QA
Other

This idea has been suggested in sphinx-doc/sphinx#6316sphinx-doc/sphinx#6316 and sphinx-doc/sphinx#6435sphinx-doc/sphinx#6435.

You can see toctree-plus in action in this project’s documentation, and the documentation for domdf-python-tools (ReadTheDocs Sphinx Theme) and whey (Furo Sphinx Theme).

Contents¶

Usage¶

Installation¶

python3 -m pip install toctree_plus --user

First add the required channels

conda config --add channels https://conda.anaconda.org/conda-forge
conda config --add channels https://conda.anaconda.org/domdfcoding

Then install

conda install toctree_plus

python3 -m pip install git+https://github.com/sphinx-toolbox/toctree_plus@master --user

Enable toctree_plus by adding the following to the extensions variable in your conf.py:

extensions = [
    ...
    'sphinxcontrib.toctree_plus',
    ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions#third-party-extensions .

Configuration¶

toctree_plus_types¶: Type: Dict[str]

Default: {"class", "function", "method"}

This determines the directive types that appear in the toctree.

.. toctree:: + Demo¶

Note

This documentation was generated with the following setting in conf.py:

toctree_plus_types = {"class", "function", "data"}

Attention

Observe that the methods of AClass do not appear in the TOC. This is a known limitation.

class AClass¶

__repr__()¶

__str__()¶

__int__()¶

__float__()¶

months = ['Jan', 'Feb', ...]¶

a_function(foo, bar, baz)¶

API Reference¶

Enhanced Sphinx TocTree which shows classes and functions as if they were sections.

Classes:

TocTreePlusCollector()

Subclass of sphinx.environment.collectors.toctree.TocTreeCollector that includes classes and functions in the toctree as if they were sections.

Functions:

setup(app)

Setup Sphinx Extension.

class TocTreePlusCollector[source]¶

Bases: TocTreeCollector

Subclass of sphinx.environment.collectors.toctree.TocTreeCollector that includes classes and functions in the toctree as if they were sections.

Methods:

process_doc(app, doctree)

Build a TOC from the doctree and store it in the inventory.

process_doc(app, doctree)[source]¶

Build a TOC from the doctree and store it in the inventory.

Parameters

app (Sphinx) – The Sphinx application.
doctree (document)

setup(app)[source]¶

Setup Sphinx Extension.

Parameters: app (Sphinx) – The Sphinx application.
Return type: Dict[str, Any]

Downloading source code¶

The toctree_plus source code is available on GitHub, and can be accessed from the following URL: https://github.com/sphinx-toolbox/toctree_plus

If you have git installed, you can clone the repository with the following command:

git clone https://github.com/sphinx-toolbox/toctree_plus

Cloning into 'toctree_plus'...
remote: Enumerating objects: 47, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 173 (delta 16), reused 17 (delta 6), pack-reused 126
Receiving objects: 100% (173/173), 126.56 KiB | 678.00 KiB/s, done.
Resolving deltas: 100% (66/66), done.

Alternatively, the code can be downloaded in a ‘zip’ file by clicking:

Clone or download –> Download Zip

Downloading a ‘zip’ file of the source code¶

Building from source¶

The recommended way to build toctree_plus is to use tox:

tox -e build

The source and wheel distributions will be in the directory dist.

If you wish, you may also use pep517.build or another PEP 517-compatible build tool.

License¶

toctree_plus is licensed under the BSD 3-Clause “New” or “Revised” License

A permissive license similar to the BSD 2-Clause License, but with a 3rd clause that prohibits others from using the name of the copyright holder or its contributors to promote derived products without written consent.

Permissions	Conditions	Limitations
Commercial use Modification Distribution Private use	License and copyright notice	Liability Warranty

See more information on choosealicense.com ➩

Copyright (c) 2020-2021 by Dominic Davis-Foster <dominic@davis-foster.co.uk>
Copyright (c) 2007-2020 by the Sphinx team.
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

View the Function Index or browse the Source Code.

Browse the GitHub Repository