Sphinx - python tips

This article takes about 2 minute to read

I recently started to educate myself more in Python. I decided that from time to time I’m going to put here some tips and tricks, things that I’ve come across that I think are interesting. These are comments from a person who has quite a lot of experience with other languages, such as Java, PHP and Matlab. I’ll put up links to these articles on twitter under hashtag #pythontips, so if you like these you can just follow the hashtag.


I started to work on a new project and since I have quite a free hand at what I’m doing, I decided to do things right. One of the most important things in any project is its documentation.

I searched for what would be nice in Python, actually there’s a huge list of different documentation generator systems on wikipedia Searching on the web I found Sphinx, seemed quite nice so I gave it a try.

In my conda installation all I had to do is:

$ conda install sphinx
# and then follow this set-up tutorial
$ sphinx-quickstart

It is going to ask you bunch of questions - if you want to generate docs from code, don’t forget to allow autodoc

Useful links:

I set up my project with following structure

├── data
├── docs        # here is Sphinx documentation
│   ├── _build
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   ├── _static
│   └── _templates
├── Makefile
├── NOTES.md
├── README.md
├── requirements.txt
├── src              # my main code
├── temp
└── tests

conf.py has all of the Sphinx config, the one that you setup in the spinhx-quickstart. Find sys.path.insert and add sys.path.insert(0, os.path.abspath('../src'))

My main project Makefile has these scripts:

# I wanted to have it called docs, but that confuses make command
# since there is a directory there already called docs - these two have to be distinct.
	# remove all old rst files except index.rst
	find ./docs -name '*.rst' ! -name 'index.rst' -type f -exec rm -f {} \;
	# generate new .rst files for docs
	sphinx-apidoc -l -F --module-first -o docs src
	# vrrrrruuummm!!! generate docs
	cd docs; make html;

	chromium-browser docs/_build/html/index.html

That’s it, I just type make doc and then make showdoc and the documentation is born. Voila!



Leave a Comment