介绍¶
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.
从其他系统转换¶
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.
使用其他系统¶
See the pertinent section in the FAQ list.