search

qutip / qutip-doc

QuTiP documentation
36 stars 58 forks source link

broken API documentation? #94

Closed jkochNU closed 3 years ago

jkochNU commented 4 years ago

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?

Capture

nathanshammah commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

jkochNU commented 4 years ago

Helpful thread on the numpydoc github, in particular this comment: https://github.com/numpy/numpydoc/issues/215#issuecomment-529037079

For me, adding

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

to custom.css solves the problem.

jakelishman commented 3 years ago

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 commented 3 years ago

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.