autotoctree

AutoTocTree Sphinx Directive Implementation

This module implements a custom Sphinx directive .. autotoctree:: that automatically generates a toctree based on your documentation folder structure. It eliminates the need to manually update toctree entries when you add or modify documentation sections.

class docfly.directives.autotoctree.AutoTocTree(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Custom Sphinx directive that automatically includes subdirectory index files in a toctree.

This directive works by:

1. Determining the current document’s location

2. Finding all subdirectories containing index files

3. Extracting titles from those index files

4. Generating a properly formatted toctree directive

The directive supports all standard toctree options (inherited from TocTree) plus additional custom options:

Parameters:

• append_ahead – Flag to append manual entries before the auto-detected entries

• index_file – Base name of index files to look for (default: “index”)

Example:

.. autotoctree::
   :maxdepth: 1
   :index_file: index

has_content = True

May the directive have content?

option_spec = {'append_ahead': <function flag>, 'caption': <function unchanged_required>, 'class': <function class_option>, 'glob': <function flag>, 'hidden': <function flag>, 'includehidden': <function flag>, 'index_file': <class 'str'>, 'maxdepth': <class 'int'>, 'name': <function unchanged>, 'numbered': <function int_or_nothing>, 'reversed': <function flag>, 'titlesonly': <function flag>}

Mapping of option names to validator functions.

run()

Execute the directive to generate the toctree.

This method is called by Sphinx when processing the directive. It creates a docutils node tree representing the toctree.

Returns:

List of nodes to be inserted into the document

derive_toctree_rst(current_file: str)

Generate the RST content for the toctree directive.

This method creates a string containing a complete toctree directive with entries for all subdirectories with index files.

Parameters:

current_file – Path to the file containing this directive

Returns:

String containing RST toctree directive

Generate the rst content:

.. toctree::
    args ...

    example.rst
    ...

Parameters:

current_file

Returns: