Sphinx Style Guide

These best practices stem from extensive experience with real-world projects. Following established conventions makes your documentation more readable while helping you avoid common pitfalls through proven patterns.

This guide presents best practices developed through years of working with Sphinx-doc, building complex documentation systems with API references, hierarchical structures, and multilingual support. By adhering to these recommendations, you can dramatically reduce repetitive work and focus on creating valuable content.

File Organization

Organize your Sphinx documentation in a logical hierarchy. A typical structure might look like:

docs/
├── source/             # Source files (.rst, .md, .ipynb)
│   ├── _static/        # Static files (CSS, images)
│   ├── _templates/     # Custom templates
│   ├── conf.py         # Sphinx configuration
│   ├── index.rst       # Main entry point
│   ├── installation/   # Section directories
│   │   └── index.rst
│   ├── usage/
│   │   └── index.rst
│   └── api/            # API documentation (can be auto-generated)
│       └── ...
└── build/              # Generated output (HTML, PDF, etc.)
    └── html/           # Generated HTML files

Naming Conventions

For consistent, maintainable documentation:

  1. Avoid spaces in filenames and directories - Use hyphens or underscores instead

  2. Prefer hyphens over underscores - Hyphens are valid in URLs, while underscores can cause issues

  3. Use kebab-case for file and directory names - For example, user-guide.rst not UserGuide.rst

  4. Stick to ASCII characters - Use English names and alphanumeric characters when possible

  5. Be consistent - Choose one naming convention and apply it throughout your project

Page Organization

Recommended: Use Folder-Based Structure

Instead of a flat hierarchy with many .rst files, organize each major documentation section as a folder with an index file:

# RECOMMENDED
docs/source/
├── user-guide/           # A directory for the "User Guide" section
│   ├── index.rst         # The main content (equivalent to user-guide.rst)
│   ├── images/           # Section-specific images
│   │   ├── screenshot1.png
│   │   └── diagram.png
│   └── examples/         # Additional subsection files
│       └── index.rst
└── index.rst             # Root document

Rather than:

# NOT RECOMMENDED
docs/source/
├── user-guide.rst        # A single file
├── screenshot1.png       # Images mixed with documents
├── diagram.png
├── examples.rst
└── index.rst             # Root document

Benefits of folder-based organization:

  1. Better organization - Related content stays together

  2. Scalability - Easy to add subsections and resources

  3. Improved navigation - Logical hierarchy for readers

  4. Maintainability - Easier to manage related assets

  5. Cleaner directories - No mixture of documents and resources

Image Management

For consistent and maintainable image handling:

  1. Create an images/ subdirectory within each documentation section:

docs/source/user-guide/
├── images/
│   ├── screenshot1.png
│   └── diagram.png
└── index.rst

  1. Reference images using relative paths:

.. image:: ./images/screenshot1.png
   :alt: Application Screenshot
   :width: 80%

  1. Consistent naming - Use descriptive, hyphenated names for images

  2. Optimize images - Compress images to reduce size without sacrificing quality

  3. Proper alt text - Always include descriptive alt text for accessibility

  4. Versioning - Update images when interfaces change, maintaining consistency with text

Multi-Language Support

If you want every HTML page to support multiple languages, the official methods are overly complicated and not recommended. Basically what it does is:

  1. Use the gentext plugin to translate the documentation into the target language - however, the translation quality is very poor.

  2. Use the multilingual feature on readthedocs.org, but this requires maintaining multiple Git repositories, which makes it difficult to keep them synchronized.

Instead, I recommend following the style defined in Page Organization, and using suffixes like _es.rst or _cn.rst to indicate different language versions of the same document. Your file structure might look like this:

tutorial
|--- index.rst      # English (default)
|--- index_es.rst   # Spanish (default)
|--- index_cn.rst   # Chinese (default)

At the beginning of each .rst file, define a reference link such as .. _en_tutorial:, .. _es_tutorial:, or .. _cn_tutorial:. Then, insert the following snippet below your top-level header to serve as a language switcher:

- :ref:`English <en_tutorial>`
- :ref:`española <es_tutorial>`
- :ref:`中文 <cn_tutorial>`

When you need to use .. autotoctree:: for non-default (non-English) sub-documents, you can specify the language-specific index file with the :index_file: option, like this:

When you need .. autotoctree:: for non-default (english) sub documents, you can use this option :index_file: index_cn.rst to locate sub documents that is in specific language::

.. autotoctree::
    :maxdepth: 1
    :index_file: index_cn.rst