Many times I have found someone’s log of an installation of some new software incredibly useful, so here’s my log from installing Sphinx a while ago.

  1. First I followed the instructions in the Sphinx tutorial here, namely:
    1. Installed using sphinx-quickstart
    2. sphinx-build -b html sourcedir builddir
    3. make html This gave me a basic html page with no content
  2. I Created a python program with some rst in the docstrings, called intercept.py, which went into the source directory
  3. I added these lines to ./source/index.rst:
    1. .. automodule:: intercept
    2. :members:
  4. I also added the following lines to ./source/conf.py: * sys.path.insert(0, os.path.abspath('.')): So it could find intercept.py * extensions = ['sphinx.ext.autodoc','sphinx.ext.pngmath']: So maths would work
  5. I ran make html and got much of the documentation into the html file, but …
  6. I got an error about “LaTeX Error: File `utf8x.def’ not found.” So I installed texlive-latex-extra as per the directions on stackoverflow
  7. I had to modify the intercept.py file before it would rerun it properly.
  8. It couldn’t find dvipng so I installed it
  9. Then success! A “make html” worked and the file in build/html/index.html now has what it needs</ol>

A best-practice example of how to use Sphinx can be found on github here.