Sphinx Documentation Generator

1. Introduction

Sphinx [1], [2] is a documentation generator which converts reStructuredText [3], [4] files into HTML websites and other formats including PDF, EPub and man.

2. Tutorials

Excellent tutorials by Brandon Rhodes: readthedocs [5], PyCon 2013 video [6], PDF [7], GitHub [8]. Numerous other tutorials are also available on the Internet [9], [10], [11], [12] [13], [14], [15]. Alfredo Deza's tutorial [10] has a sample Sphinx project.

3. HTML themes

The default theme is really ugly. However, Sphinx supports changing the appearance of its HTML output via themes [16], [17]. A nice collection of themes comes with installation. In the default Anaconda installation they are in

Win:

C:\Anaconda3\Lib\site-packages\sphinx\themes

Mac:

~/anaconda/lib/python3.4/site-packages/sphinx/themes/

or under the virtual environments directory

Win:

C:\Anaconda3\Lib\site-packages\conda_env

Mac:

~/anaconda/envs/py27/lib/python2.7/site-packages/sphinx/themes/

The following themes are in my installation [16]:

agogo
basic
bizstyle
default
epub
haiku
nature
pyramid
scrolls
sphinxdoc
traditional

Many more themes are on the Internet.

4. reStructuredText tool support

Here [18] is a nice collection of

• reStructuredText parsers in other languages
• Other 3rd party converters
• Free Editors
• Dedicated reStructuredText Editors
• Web Services
• Blogging frameworks
• More . . .

References

1. Sphinx (documentation generator)
2. Sphinx overview
3. Official reStructuredText website with reference pages
4. Python Enhancement Proposal (PEP) 287: reStructuredText Docstring Format
5. Brandon Rhodes, Welcome to the Sphinx Tutorial!
6. Brandon Rhodes, Documenting Your Project in Sphinx - YouTube
7. Brandon Rhodes, Brandon's Sphinx Tutorial (PDF)
8. Brandon Rhodes, Brandon Rhodes - GitHub
9. Documenting Your Project Using Sphinx
10. Alfredo Deza, Easy and beautiful documentation with Sphinx
11. Use Sphinx to automatically create Python documents
12. Documenting Your Project Using Sphinx
13. Quick reStructuredText
14. Restructured Text (reST) and Sphinx CheatSheet
15. Inline markup
16. HTML theming support
17. Sphinx themes
18. reStructuredText tool support