sphinx

Sphinx Best Practices

Sphinx is the definitive tool for Python project documentation. This guide outlines the essential workflow and best practices for creating intelligent, beautiful, and maintainable docs. Always prioritize consistency within your project over strict adherence to external guides, but default to these modern standards.

1. Project Setup and Structure

Establish a clean, predictable documentation structure from the start.

1.1. Use a Virtual Environment

Always isolate your documentation build dependencies. This prevents conflicts and ensures reproducible builds.

# ❌ BAD: Installing Sphinx globally
pip install sphinx

# ✅ GOOD: Create and activate a virtual environment
python -m venv .venv/docs
source .venv/docs/bin/activate  # On Windows: .venv\docs\Scripts\activate
pip install sphinx sphinx-autobuild myst-parser sphinx-rtd-theme sphinx.ext.napoleon

1.2. Standard Directory Layout

Place all documentation source files in a dedicated docs/ directory at your project root.

my_project/
├── .venv/
├── my_package/
│   └── __init__.py
│   └── module.py
├── docs/
│   ├── conf.py
│   ├── index.md        # Or index.rst
│   ├── tutorial/       # For manual narrative content
│   │   └── getting_started.md
│   ├── api/            # For auto-generated API docs (managed by apidoc)
│   │   └── my_package.rst
│   ├── _static/        # Custom static files (images, CSS)
│   ├── _templates/     # Custom Jinja2 templates
│   └── Makefile        # Or make.bat for Windows
├── README.md
├── CHANGELOG.md
├── LICENSE
└── pyproject.toml

1.3. Initialize with sphinx-quickstart

Use the quickstart tool once to scaffold your docs/ directory. Accept the defaults, then customize.

# From your project root:
cd docs
sphinx-quickstart

1.4. Prefer MyST Markdown for New Content

For narrative documentation, MyST Markdown (.md) is more approachable than reStructuredText (.rst) while retaining Sphinx's powerful features. Use it for all new manual content.