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.
- First I followed the instructions in the Sphinx tutorial here, namely:
- Installed using sphinx-quickstart
- sphinx-build -b html sourcedir builddir
- make html This gave me a basic html page with no content
- I Created a python program with some rst in the docstrings, called intercept.py, which went into the source directory
- I added these lines to ./source/index.rst:
.. automodule:: intercept
- 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
- I ran make html and got much of the documentation into the html file, but …
- I got an error about “LaTeX Error: File `utf8x.def’ not found.” So I installed texlive-latex-extra as per the directions on stackoverflow
- I had to modify the intercept.py file before it would rerun it properly.
- It couldn’t find dvipng so I installed it
- 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.