Features#

The Sphinx documentation template key features:

  • 💯 Free & open-source.

  • ✍️ Write in Markdown or reStructuredText.

  • 🏗️ Comes with popular Sphinx extension for sitemaps, redirects, diagrams, etc.

  • 👅 Localization (i18n) support.

  • 😀 Sane configuration defaults and best practices.

  • 🎨 VS Code support: recommended extensions, settings and formatting.

  • ⚒️ Live reload on change.

  • 💾 Build to multiple outputs.

  • 👍 Works out-of-the-box.

Some of the features are described in more detail below.

Mixing MD and RST#

The template configures Sphinx to mix writing in Markdown and reStructuredText syntax freely. The detection is based on the .md or .rst file extension.

Multiple outputs#

The template supports output to multiple formats (called builders in Sphinx). By default, only HTML-based builders are tested:

  • html - from features.md creates features.html

  • dirhtml - from features.md creates features/index.html making nicer URLs like (features/) because index.html is served automatically.

  • singlehtml - all documents are in a single long HTML page

Builders are configured with DEFAULT_BUILDER and BUILDERS variables in noxfile.py.

Preview#

The template can launch a web server for local development, watch for document changes, rebuild HTML pages, and refresh a browser automatically.

See preview task.