generate_rst Module#

generate_rst.py

A utility module for generating reStructuredText (.rst) files for Python modules to be used with Sphinx documentation.

This script scans a given directory for Python modules (excluding specified directories) and automatically creates corresponding .rst files using the .. automodule:: directive. These files are intended to be included in a Sphinx documentation build.

Usage:

Run this script as a standalone module to generate .rst files:

$ export PYTHONPATH=$PYTHONPATH:. $ python utils/generate_rst.py

This will:

  • Search for all .py files (excluding __init__.py) in the specified source directory.

  • Skip excluded directories like tests, build, and __pycache__.

  • Output .rst files to the appropriate subdirectories in source/.

Functions:
  • generate_module_rst(module_path, output_dir):

    Generates a .rst file for a single module using the Sphinx automodule directive.

  • find_modules(root_dir, current_dir, exclude_dirs=None):

    Recursively finds Python modules in a directory, excluding specified directories.

Note

The generated .rst files are intended to be included in the Sphinx build.

utils.generate_rst.find_modules(root_dir: str, current_dir: str, exclude_dirs: list[str] | None = None) → list[str][source]#

Recursively finds Python modules (.py files) within a given root directory.

Parameters:

  • root_dir (str) – The root directory of the project.

  • current_dir (str) – The current directory to search.

  • exclude_dirs (list, optional) – A list of directory names to exclude. Defaults to None.

Returns:

A list of module relative paths (e.g., [‘utils/file_ops’]).

Return type:

list

utils.generate_rst.generate_module_rst(module_path: str, output_dir: str) → None[source]#

Generates a reStructuredText file for a Python module.

Parameters:

  • module_path (str) – The relative path to the Python module (e.g., ‘utils/file_ops’).

  • output_dir (str) – The directory where the .rst file will be created.

utils.generate_rst.run_generator(git_root: str | None, excluded_directories: list[str]) → None[source]#

Recursively finds Python modules and generates corresponding .rst files.

Parameters:

  • git_root (str) – The root directory of the project.

  • excluded_directories (list) – A list of directory names to exclude.