Overhauling the internals of a mathematical library is no good if no other
developers on the team know how to use the new systems you’ve put in place, and
don’t know why you’ve made the choices you’ve made. In the last week I’ve been
writing a new QuTiP developers’ guide to the new data layer that I’m creating
as part of my Google Summer of Code project, which has involved learning a lot
more about the Sphinx documentation tool, and a little bit of GitHub
esoterica.
Currently we don’t have a complete plan for how this guide will be merged into
the QuTiP documentation, and where exactly it will go, so for now it is hosted
on my own GitHub repository. I have also put up a properly
rendered version on a GitHub pages site linked to the
repository.
My Sphinx conf.py file for this repository is not (at the time of
commit 0edf49e) very exciting. Fortunately, Sphinx largely just
works out-of-the-box as one would expect from a mature Python project. Perhaps
the boldest part of that file is the intersphinx_mapping dictionary, which
uses the intersphinx built-in to link to other projects’ documentation also
built with Sphinx.
Right now, the intersphinx documentation is perhaps a little lacking, and
sometimes seems to just involve some hope (and some disappointment). In
particular, I have several external references set up as
1
2
3
4
5
6
7intersphinx_mapping = {
'qutip': ('http://qutip.org/docs/latest/', None),
'python': ('https://docs.python.org/3', None),
'numpy': ('https://numpy.org/doc/stable/', None),
'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
'cython': ('https://cython.readthedocs.io/en/latest/', None),
}