DOCS: variable names are merged with description

[surchs]

In the API docs, the variable names and their descriptions are not separated by a space or colon:

Screenshots or screencasts of the bug in action

e.g. the docs for datashader.transfer_functions.shade:

Other info

This makes the docs hard to read and is a bit confusing (e.g. I stumbled on this after looking for aggDataArray for a while).
I believe this issue is similar or related to a numpydoc issue related to upgrading sphinx: numpy/numpydoc#215

[jbednar]

Damn. Yes, there used to be a colon there. Any hope some could follow what's outlined in that numpydoc issue and make a PR on our theme CSS (https://github.com/pyviz-dev/sphinx_holoviz_theme)?

[scottclowe]

Here is my understanding of this issue.

When Sphinx moved from 1.x to 2.0, they added a new entry to the core style sheet _build/html/_static/basic.css, which reads:

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

That means that in Sphinx 2 and above, the : separator is now automatically added before the type entry (which they call a classifier) of the documentation due to the :before: CSS. Previously (in sphinx<2), the style sheet didn't do this and : was expected to be added as part of the HTML by things (like numpydoc) which generate the parameter lists.

Consequently, newer versions of numpydoc don't add : to the HTML because they expect the sphinx CSS to add it. Unfortunately, the requirements for numpydoc have stayed at sphinx>=1.6.5 and not increased to reflect the fact that they rely on a CSS feature from sphinx 2, so you can end up installing an incompatible combination of numpydoc and sphinx if you're on Sphinx 1.x and using a newer numpydoc release.

The simplest way to resolve the issue to build your documentation on sphinx>=2.0.0.

I have seen this issue tends to arise when documentation is built on readthedocs. As part of its default build process, readthedocs first installs sphinx<2 and then installs your requirements. That means that you don't get the latest version of sphinx unless you specify a minimum sphinx version higher than that in your requirements.

I'm not going to make a PR to fix this because I can't see where datashader specifies its documentation requirements, and I don't understand how your conda.recipe works.

[jbednar]

Thanks! I imagine we'll have other issues when we upgrade sphinx, but that definitely helps us get started!

[jbednar]

Fixed; see https://pyviz-dev.github.io/datashader/api.html#datashader.transfer_functions.shade