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


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


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

See the pertinent section in the FAQ list.


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

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.


Usage
=====

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