Notes with sphinx

Notes from conferences, minutes from a teleconf, ideas, etc.

Set up docs directory and (see other post).

Add math support, to array ‘extension’ in, e.g. ‘sphinx.ext.pngmath’. Looks like

extensions = [

Edit index.rst.




.. toctree::
:maxdepth: 4

Mljet 2015


.. toctree::
:maxdepth: 4

Lausanne 2015

One rst file for each meeting. E.g. euclid-lausanne-2015.rst:



Jarle Brinchmann, legacy


Large number of WG (Milky Way, AGN, local Universe, extra-solar planets,
strong lensing, theory, cosmological simulations, SN + transients, galaxy
clusters, primeval universe)


.. bibliography:: astro.bib
:style: mystyle
:encoding: utf

astro.bib is bibtex file
:cited: only display cited references (other option :all:)
:style: see
encoding: utf, do not interpolate any latex special characters. Necessary if ‘%’ in url links, but
annoying for math mode in titles, LaTeX accents in names etc.

Need to add missing abbreviations to bibtex file, e.g.:

@string{apjs = “APJS”}

Further problems:
– missing title
– missing booktitle
– missing journal
pages = {3-}, needs to be {3-+} [error message does not show line in bibtex file!]

make html or make latexpdf
can take a long time for long (several hundred) bib entries.

# pybtex code following:
# and

from import Style
# Other styles: alpha, plain, unsrtalpha
from import (
join, field, optional, sentence, href )
from pybtex.plugin import register_plugin

class MyStyle(Style):

def format_web_refs(self, e):
# based on urlbst output.web.refs
# Adds adsurl with link
return sentence(capfirst=False) [
optional [ self.format_url(e) ],
optional [ self.format_adsurl(e) ],
optional [ self.format_eprint(e) ],
optional [ self.format_pubmed(e) ],
optional [ self.format_doi(e) ],

def format_url(self, e):
# based on urlbst format.url
return href [

def format_adsurl(self, e):
# based on urlbst format.url
return href [
‘ads link’

register_plugin(‘’, ‘mystyle’, MyStyle)


vi and sphinx table formatting

sphinx rst tables look great when formatted in html or pdf, but they require some effort to type. Here is an example:

| Scale    | Convergence  |
| 0.1 Mpc: | 0.1          |
| 1 Mpc:   | kappa ~ 0.03 |
| 3 Mpc    | 0.01         |

The delimiters need to have exactly the same length in each row, encompassing the text, and the crosses, equal signs and dashes have to be at right places. If a column gets enlarged, the whole table has to be changed, which is a pain.

Luckily, vi has extensions that automatically transforms text in an rst file into a table, and reformats an existing table that has been edited. As usual, installing and making it work took more time than I thought. The package is available for download here, and has a description how to install it. However, it turned out not to be complete, and I had to fiddle around for quite a while until it worked. Here are the steps I needed to do:

1. Install vim_bridge. I used pip. Since I have more than one python versions on my system (Mac OS 10.9.5), and I didn’t know which version is used by vim, I installed it under all versions:

pip-2.7 install vim_bridge
pip-3.3 install vim_bridge
pip-3.4 install vim_bridge

2. Download vim-rst-tables. My default directory to download software from the internet is ~/share.

cd ~/share
git clone git://

3. Copy the extension file. I had to create the vim filetype plugins directory (ftplugin) first.

mkdir ~/.vim/ftplugin
cp ftplugin/rst_tables.vim ~/.vim/ftplugin

4. Unfortunately, the promised commands to create and reformat rst tables (“,,c” and “,,f”) did not do anything in vim. To find out this hack took me the longest. It turned out that the plugin was found (in vim, after loading a .rst file, type
“:scriptnames”, without the quotation marks, the newly added rst_tables.vim should appear in the list), the filtype was correctly recognized as rst (type “set ft”), and rst_tables.vim was indeed parsed (add some random characters to a line in that file, and vim will on start give an error message). I also realized that the long command names did work (type “call ReformatTable()”). To get the key shortcuts work, I had to add to the last part of rst_tables.vim, after the line “if !exists(“no_plugin_maps”) && !exists(“no_rst_table_maps”)” the following line:

:let mapleader = ","

I don’t know whether this is only required on my system, but here you are. It’s finally working. It took me more than an hour to get it working, so according to, if this plugin saves me 30 seconds of manual table reformatting once a week over the next five years, it was totally worth it!

Quick setup of sphinx documentation

sphinx is a great and versatile tool. Not only does it create simple but easy to read (python) code documentation. One can use sphinx to produce a readme, a manual, notes, minutes, etc., that go beyond the simple ascii format with just a little bit of effort. Most of the content of existing ascii files are already in a suitable format for sphinx. Compared to LaTeX, the extra work beyond actually writing the content is minimal. In fact, sphinx can automatically produce quite decent LaTeX output. And html, xml and other formats.

However, I found it a bit tricky to set up a sphinx directory, and it took me half a day to get going. Online documentation is quite decent, but did not present in a concise and easy-to-understand way what I wanted, that is, to quickly create a sphinx parent document for my python coding projects. So here is a summary of the steps I needed to do.

First, the case where existing files are to be included in a sphinx document (file index.rst). For example, python scripts and modules that already have sphinx-compatible documentation.

  1. Install sphinx if not already existing, for example using port (on a Mac) or pip.
  2. From the directory where the scripts are located, say ‘/path/to/scripts’, create a sub-directory ‘docs’ (or any other name).
  3. In /path/to/scripts, run

    sphinx-apidoc -A “Author name” -H “Project name” -F -o docs .

    On some systems, the command might be sphinx-apidoc-X.Y’ where ‘X.Y’ is the active python version. This creates various files and directories in ‘docs’, in particular the configuration file ‘’, and the actual sphinx parent document ‘index.rst’, which automatically contains references to all scripts in ‘/path/to/scripts’.

  4. Add path to the scripts to the sphinx configuration file docs/ From ‘docs’, the relative path is ‘..’, and the line to be added is:

    sys.path.insert(0, os.path.abspath(‘..’))

  5. [optional] Add path(s) to further scripts, e.g. modules that are included in the python scripts. In ‘docs/’, add a new line:

    sys.path.insert(0, os.path.abspath(‘/path/to/mores/files’))

  6. In ‘docs’, run

    make html

Done! The file ‘_build/html/index.html’ (in ‘docs/’) contains the html version of the code documentation. Open this file in your browser, e.g. from Terminal on a Mac:

open _build/html/index.html

Other output format can be created by replacing ‘html’ in step 6 with e.g. ‘latex’, ‘latexpdf’, etc. See ‘docs/Makefile’ for all possible options.

Further posts will describe how to quickly create conference (or other) notes, include references using bibtex, and actually create a sphinx (html) document containing all references with links to the papers from a bibtex file.