Li-Pro.Net Sphinx Primer

PREAMBLE

How to write Li-Pro.Net documentation with Sphinx.

Excerpts from the Sphinx Tutorial by Eric Holscher and Documentation Style Guide by Bareos GmbH & Co. KG and others. See [Has19] for an introduction to Sphinx.

This documentation is built using Sphinx, a static-site generator designed to create structured, semantic, and internally consistent documentation. Source documents are written in reStructuredText, a semantic, extensible markup syntax similar to Markdown. reStructuredText is a better tool than Markdown for documentation.

Note

Sphinx and reStructuredText can be very flexible. For the sake of consistency and maintainability, this how to guide is highly opinionated about how documentation source files are organized and marked up.

Version history

Table 1 Li-Pro.Net Sphinx Primer Document Revisions

Version

Change

Passed

Date

0.0.5

extended content in chapter “Extensions”, template finetuning, extend local extension

Stephan Linz

2020-10-01

0.0.4

initial content in chapter “Concepts”

Stephan Linz

2020-09-14

0.0.3

initial content in chapter “Extensions”

Stephan Linz

2020-09-11

0.0.2

initial content in chapters “Cheat Sheet” and “Themes”

Stephan Linz

2020-09-08

0.0.1

base document skeleton

Stephan Linz

2020-09-08

0.0

preliminary, project created

Stephan Linz

2020-09-05