This is the documentation for the Sphinx documentation builder. Sphinx is a tool that translates a set of reStructuredText source files into various output formats, automatically producing cross-references, indices, etc. That is, if you have a directory containing a bunch of reST-formatted documents (and possibly subdirectories of docs in there as well), Sphinx can generate a nicely-organized arrangement of HTML files (in some other directory) for easy browsing and navigation. But from the same source, it can also generate a PDF file using LaTeX.

The focus is on hand-written documentation, rather than auto-generated API docs. Though there is support for that kind of documentation as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at Epydoc, which also understands reST.

For a great «introduction» to writing docs in general – the whys and hows, see also Write the docs, written by Eric Holscher.

Conversión desde otros sistemas

Esta sección está pensada para recoger consejos útiles para aquellos que quieran migrar a reStructuredText/Sphinx de otros sistemas de documentación.

  • Gerard Flanagan has written a script to convert pure HTML to reST; it can be found at the Python Package Index.

  • For converting the old Python docs to Sphinx, a converter was written which can be found at the Python SVN repository. It contains generic code to convert Python-doc-style LaTeX markup to Sphinx reST.

  • Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx markup; it is at GitHub.

  • Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents to Sphinx: odt2sphinx.

  • To convert different markups, Pandoc is a very helpful tool.

Usar con otros sistemas

Ver la seccion pertinente en la lista de FAQ.

Requisitos previos

Sphinx needs at least Python 3.5 to run. It also depends on 3rd party libraries such as docutils and jinja2, but they are automatically installed when sphinx is installed.


See Getting Started for an introduction. It also contains links to more advanced sections in this manual for the topics it discusses.