Installing Sphinx

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 this line to ./source/index.rst:
    .. automodule:: intercept
    :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

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

2 thoughts on “Installing Sphinx

  1. The day the routers died – who put the 4 inch nail in the circuit breaker and poured coffee over the servers? A. The Bastard Operator from Hell

Leave a Reply