sphinx / doc / intro.rst

georg.brandl 186cf92 

georg.brandl b3fff67 

georg.brandl 72370f1 

Georg Brandl cec7b81 

georg.brandl 186cf92 
georg.brandl f6b03bc 
Georg Brandl 86e7ddb 

georg.brandl f6b03bc 
georg.brandl a895655 

Georg Brandl eb9cb40 

georg.brandl a895655 

georg.brandl e5cf123 
georg.brandl a895655 
Georg Brandl fd56ff4 

georg.brandl a895655 
Georg Brandl ca1aea7 

georg.brandl 186cf92 

Georg Brandl a2feb99 

georg.brandl b3fff67 

Georg Brandl a2feb99 

georg.brandl b3fff67 

Georg Brandl ca1aea7 

georg.brandl b3fff67 
Georg Brandl 816796d 

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
LaTeX file that you can compile into a PDF version of the documents, or a
PDF file directly using `rst2pdf <>`_.

The focus is on hand-written documentation, rather than auto-generated API docs.
Though there is support for that kind of docs 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.

Conversion from other systems

This section is intended to collect helpful hints for those wanting to migrate
to reStructuredText/Sphinx from other documentation systems.

* Gerard Flanagan has written a script to convert pure HTML to reST; it can be
  found at `BitBucket

* 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 `Google Code <>`_.

Use with other systems

See the :ref:`pertinent section in the FAQ list <usingwith>`.


Sphinx needs at least **Python 2.4** to run, as well as the docutils_ and
Jinja2_ libraries.  Sphinx should work with docutils version 0.5 or some
(not broken) SVN trunk snapshot.  If you like to have source code highlighting
support, you must also install the Pygments_ library.

.. _reStructuredText:
.. _docutils:
.. _Jinja2:
.. _Pygments:


See :doc:`tutorial` for an introduction.  It also contains links to more
advanced sections in this manual for the topics it discusses.