Home

Recent
Archive

Numerical experiments, Tips, Tricks and Gotchas

Numerically speaking

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

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

 

© Nikolai Shokhirev, 2012-2017

email: nikolai(dot)shokhirev(at)gmail(dot)com

Count: