Overview

An opinionated template for creating a modern Sphinx documentation project. Write in Markdown or reStructuredText, translate to multiple languages, boost with popular extensions, and enjoy automatic live reload on change.

Default blank Sphinx documentation project needs a lot of configuration, fine-tuning, trials, and fails before setting up everything for best results. This template results from the best practices and knowledge we gained by providing Documatt's technical writing services.

File layout structure

Sphinx Documentation Template follows a fairly specific file system layout. This standardized structure eases maintenance and switching between multiple projects.

All tasks, like build and preview, are in the noxfile.py file, and this documentation assumes the structure.

.
├── build/                  ┐
│   └── <builder>/          | Output files
│       └── <language>/     |
│           └── ...         ┘
├── source/                 ┐
│   ├── _static/            |
│   │   ├── favicon.svg     |
│   │   └── logo.svg        |
│   ├── _templates/         | Sphinx project sources
│   ├── conf.py             | (documents, images, conf.py)
│   ├── index.md            |
│   ├── overview.md         |
│   └── ...                 ┘
├── .gitignore              ┐
├── CHANGELOG.md            |
├── LICENSE                 |
├── noxfile.py              | Meta files
├── package-lock.json       |
├── package.json            |
└── pyproject.toml          ┘

The files and folders are for three purposes:

• Sphinx project sources. Regular files found in Sphinx projects like .md, .rst, images, conf.py.

• When built by tasks, output goes to (by default) to build/.

• Meta files. Not the documentation itself. Like dependencies in pyproject.toml, license, standard .gitignore, etc.

Everything except the output directory should be versioned.

Output directory structure

The output directory (the OUTDIR) is organized to <builder>/<language>/ directory layout.

For example, for builders dirhtml and html, and languages en, cs, and he, the following folder and files are created (irrelevant files omitted):

.
├── build/
    ├── dirhtml/
    │    ├── cs/
    │    │    ├── index.html
    │    │    ├── sample/
    │    │    │   └── index.html
    │    │    ├── search/
    │    │    │   └── index.html
    │    │    └── sections/
    │    │    └── index.html
    │    ├── en/
    │    │   ├── index.html
    │    │   ├── sample/
    │    │   │   └── index.html
    │    │   ├── search/
    │    │   │   └── index.html
    │    │   └── section/
    │    │   └── index.html
    │    └── he/
    │        ├── index.html
    │        ├── sample/
    │        │   └── index.html
    │        ├── search/
    │        │   └── index.html
    │        └── sections/
    │        └── index.html
    └── html/
        ├── cs/
        │   ├── index.html
        │   ├── sample.html
        │   ├── search.html
        │   └── sections.html
        ├── en/
        │   ├── index.html
        │   ├── sample.html
        │   ├── search.html
        │   └── sections.html
        └── he/
            ├── index.html
            ├── sample.html
            ├── search.html
            └── sections.html