What is Sphinx?

From http://sphinx-doc.org:

  • Sphinx is a tool that makes it easy to create intelligent and beautiful documentation.
  • It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well.


... a great tool that actually makes programmers want to write documentation!

Sphinx Philosophy

Sphinx is a documentation generator. This means it takes plain-text files in reStructuredText format and transformes it into HTML, PDF, and any other output format.

reST -> Sphinx -> HTML (PDF, eBook, ...)

So as a user of Sphinx, your main job will be writing these text files with reStructuredText which is similar to Wiki languages like Markdown.

Sphinx Advantages

  • Documents are written as plain text files.
  • Output formats will be generated by Sphinx: HTML, PDF, eBook.
  • Markup language used (reST) is similar to Wiki languages (Markdown, Textile, ...).
  • Layouts can be replaced, many default layouts available.
  • Writer concentrates on content, layout and output comes from Sphinx.
  • Autogenerating documentation from source code.
  • Syntax highlighting for many formats (Python, XML, ...).
  • Cross-references to parts of the documenation (sections, code, glossary, ...) and automatic indices.
  • Version control (GitHub) can be used for collaborative work and keeping track of different document versions.
  • The documentation is part of the source code repository.