autotoctree

Automatic Table of Contents (TOC) generator for Sphinx documentation.

This module provides tools to automatically generate Sphinx toctree directives based on your documentation’s folder structure. Instead of manually maintaining TOC entries when adding or removing documentation pages, this functionality examines your directory structure and builds appropriate toctree directives with correct titles extracted from each document.

The main workflow involves:

1. Finding directories containing index files (rst, md, or ipynb)

2. Extracting the title from each index file

3. Generating a properly formatted toctree directive linking to all child pages

This approach ensures your documentation navigation stays organized and up-to-date with minimal manual intervention.

exception docfly.autotoctree.IndexFileNotFoundError

class docfly.autotoctree.PageFolder(dir: Path, index_filename: str)

Represents a folder containing an index document with a title.

A PageFolder typically maps to a documentation section with an index file (index.rst, index.md, or index.ipynb) that contains a title. This class provides methods to extract the title, find child page folders, and generate a toctree directive linking to those children.

The index file is searched in this order:

1. .rst (reStructuredText)

2. .ipynb (Jupyter Notebook)

3. .md (Markdown)

Parameters:

• dir – Path to the directory containing the index file

• index_filename – Base name of the index file without extension (default: “index”)

Example folder structure:

docs/sources/
docs/sources/index.rst
docs/sources/document-1/index.rst
docs/sources/document-2/index.ipynb
docs/sources/document-3/index.md
docs/sources/document-3/...

Usage:

# Create a PageFolder for the main docs directory
main_folder = PageFolder.new(dir=Path("docs/sources"))

# Generate toctree directive
toc_content = main_folder.toc_directive()

# Result will be:
# .. toctree::
#     :maxdepth: 1
#
#     Document 1 <document-1/index>
#     Document 2 <document-2/index>
#     Document 3 <document-3/index>

classmethod new(dir: Path, index_filename: str = 'index')

Create a new PageFolder instance with resolved index file.

This factory method creates a PageFolder instance and resolves which type of index file exists (.rst, .ipynb, or .md).

TODO: 现在有一个问题是作为包含 .. autotoctree: 的父节点必须要是 RST, 你不能在 Notebook 里包含这个. TODO: 我们需要将父节点的 index_filename 和 discover 阶段的子目录的 index_file 区分开来, 以后会实现.

property path_index_rst: Path

Get the absolute path to the potential reStructuredText index file.

property path_index_ipynb: Path

Get the absolute path to the potential Jupyter Notebook index file.

property path_index_md: Path

Get the absolute path to the potential Markdown index file.

property path_str

Get the relative path string used in toctree entries.

get_title_from_rst() → str | None

Extract title from a reStructuredText file.

Finds the first section title by looking for underline patterns (====, —-, etc.) and returns the text line above it.

Also handles .. include:: directives by replacing them with the content of the included file.

Returns:

Extracted title or None if no title found

get_title_from_md() → str | None

Extract title from a Markdown file.

Returns:

Extracted title or None if no title found

Raises:

NotImplementedError – This method is not implemented yet

get_title_from_ipynb() → str | None

Extract title from a Jupyter Notebook file.

Looks for a title in:

1. The first markdown cell with a level 1 heading (# Title)

2. A raw reStructuredText cell with a title and underline

Returns:

Extracted title or None if no title found

property title: str | None

Title for the first header in the index file

property child_page_folders: List[PageFolder]

Find all valid child page folders.

Searches for directories containing index files with valid titles and returns them as PageFolder instances.

toc_directive(maxdepth=1)

Generate a toctree directive for the child page folders.

Creates a properly formatted reStructuredText toctree directive that includes all child pages with their titles.

Parameters:

maxdepth – Maximum depth for the toctree directive

Returns:

Complete toctree directive as a string