
Introduction
************

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 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 Google Code.

* 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.


Use with other systems
======================

See the *pertinent section in the FAQ list*.


Prerequisites
=============

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

If you use **Python 2.4** you also need uuid.


Usage
=====

See *First Steps with Sphinx* for an introduction.  It also contains
links to more advanced sections in this manual for the topics it
discusses.
