broken API documentation?

[jkochNU]

It looks like the latest API documentation has a problem (unless this is a display problem on my end only - in which case I must apologize).

Example: looking at http://qutip.org/docs/latest/apidoc/classes.html#qobj , what I see as the first two Parameters of Qobj is:
inptarray_like
dimslist

I suspect this should be inpt: array_like and dims: list
Is this an issue related to the space preceding the colon in the corresponding docstrings in the qutip source code?

[nathanshammah]

As you spotted, it seems related to having a space before and after the : as in here.

The two spaces should be a PEP style directive, and seems used also by other libraries, see NumPy here.

It would be great to find what's messing with this. It applies only to the latest documentation (4.4).

[jkochNU]

I suspect the problem might originate from sphinx_rtd_theme. If I remove html_theme = "sphinx_rtd_theme" in conf.py and build using just the default sphinx theme, then results look as expected (when including the space before the colon).

[jkochNU]

Found this thread on the github for sphinx_rtd_theme: readthedocs/sphinx_rtd_theme#750
There, blame was being put on incompatibilities between the rtd theme and Sphinx 2, if I understand correctly.

[jkochNU]

Helpful thread on the numpydoc github, in particular this comment: numpy/numpydoc#215 (comment)

For me, adding

.classifier:before {
    font-style: normal;
    margin: 0.2em;
    content: ":";
}

to custom.css solves the problem.

[jakelishman]

This is related to a sphinx_rtd_theme/docutils==0.17 incompatibility. The solution is to force version sphinx_rtd_theme>=0.5.2 (currently only on pip, not conda), which correctly handles the dependency. This will be fixed in the 4.6 release.

[jakelishman]

This is now fixed in the released 4.6.0 documentation release. When we've got slightly easier methods for deploying the documentation to the website it'll be easier to "backport" fixes to previous releases, but right now our method isn't ideal so I'll leave the older versions as-is.