Skip to content

Latest commit

 

History

History
executable file
·
70 lines (57 loc) · 2.92 KB

README.md

File metadata and controls

executable file
·
70 lines (57 loc) · 2.92 KB

Sphinx HTML Documentation Generation

The src/docs directory contains a Sphinx project that generates HTML documentation for the Python codebase. Sphinx is a documentation generator that converts reStructuredText files and Python docstrings into HTML documentation with cross-references, search functionality, and more.

Directory Structure

  • make.bat - Batch file to build the project on Windows.
  • Makefile - Used by make (see Make Commands below) - Makefile
  • README.md - This document
  • source - Contains Sphinx configuration and source files.
    • _static - Directory for static resources (images, CSS, etc.).
      • Images - Our own custom images, Sphinx can find.
    • _templates - Directory for custom HTML templates.
    • themes - Directory for custom Sphinx themes.
      • pronouns2 - Our own Sphinx theme
    • conf.py - Contains Sphinx configuration file
    • index.rst- Main Sphinx documentation index.
    • faq.rst - FAQ section in reStructuredText format.
    • *.rst - Generated by sphinx-apidoc -f -o ./docs/source .
  • build - Sphinx generated HTML documentation
    • doctrees - Directory for cached doctree files.
    • html - Directory for generated HTML documentation.
      • _sources - Directory for plaintext .rst source links in HTML.
      • _static - Static resources copied during HTML build.
        • Images - Copied custom images.
      • *.htm - HTML files generated by make html

Make Commands

The following make targets are available:

  • make help - Print this help
  • make view - Build everything; view HTML doc
  • make all - Clean everything and rebuild HTML documentation
  • make apidoc - Generate API documentation
  • make linkcheck - Check external links for integrity
  • make html - Generate HTML documentation
  • make clean - Remove intermediate build files
  • make distclean - Remove non-shipping files, including the build directory
  • make maintainer-clean - Remove all generated files, including shipped HTML files

Quick Start

For a complete rebuild of the HTML documentation, simply run:

make all

The generated HTML documentation will be available in build/html/index.htm.

For Developers

If you've made changes to Python docstrings or documentation source files:

  1. The make all command will handle everything automatically
  2. Individual steps can be run manually if needed using the commands above
  3. The documentation is automatically generated from:
    • Python docstrings in the source code
    • ReStructuredText (.rst) files in the source directory
    • Configuration in source/conf.py

For Project Maintainers

This documentation system integrates with the project's main build system. Higher-level makefiles can simply call make all in this directory to generate complete documentation.