# sphinx / doc / intro.rst

 georg.brandl 186cf92 2008-03-09 georg.brandl b3fff67 2008-03-12 georg.brandl 72370f1 2008-08-23 Georg Brandl cec7b81 2010-05-22 georg.brandl 186cf92 2008-03-09 georg.brandl f6b03bc 2008-03-18 Georg Brandl 86e7ddb 2010-02-28 georg.brandl f6b03bc 2008-03-18 georg.brandl a895655 2008-09-09 Georg Brandl eb9cb40 2009-06-10 georg.brandl a895655 2008-09-09 georg.brandl e5cf123 2008-09-24 georg.brandl a895655 2008-09-09 Georg Brandl fd56ff4 2009-08-04 georg.brandl a895655 2008-09-09 Georg Brandl ca1aea7 2010-02-28 georg.brandl 186cf92 2008-03-09 Georg Brandl a2feb99 2010-07-10 georg.brandl b3fff67 2008-03-12 Georg Brandl a2feb99 2010-07-10 georg.brandl b3fff67 2008-03-12 Georg Brandl ca1aea7 2010-02-28 georg.brandl b3fff67 2008-03-12 Georg Brandl 816796d 2010-03-01   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 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 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 . Prerequisites ------------- 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: http://docutils.sf.net/rst.html .. _docutils: http://docutils.sf.net/ .. _Jinja2: http://jinja.pocoo.org/2/ .. _Pygments: http://pygments.org/ Usage ----- See :doc:tutorial for an introduction. It also contains links to more advanced sections in this manual for the topics it discusses. 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.