API docs look different with Sphinx 2.0

[Bultako]

Problem

The HTML API docs generated with Sphinx 2.0 do not display the colons separating parameter names and types. Moreover, the look has significantly changed.

Expected Results

Obtained Results

Environment Info

• Python Version: 3.7
• Sphinx Version: 2.0.1
• RTD Theme Version: 0.4.3

More Info / Related links

gammapy/gammapy#2164
sphinx-doc/sphinx#6400

[IgnacioJPickering]

Setting html4_writer=True in sphinx's conf.py seems to work as a temporary fix.

[agjohnson]

Is this python domain API output?

Thanks for the workaround for now! 🎉

[lesteve]

As far as I am concerned the most problematic thing by far is the lack of spacing between the parameter name and the parameter type. This has lead confusion for our users. For example, in the top post example, people would try to use morphologystr as parameter, rather than morphology.

The spacing issue has been reported in #746 and there is an associated PR #747 that will fix it. Unfortunately this PR does not seem to have received too much attention. I am guessing part of the reason is because it is a wide-reaching change.

For my project, html4_writer = True was not fixing this spacing issue. The simplest fix I found was dask/dask-jobqueue#301, i.e. add this in conf.py:

# Temporary work-around for spacing problem between parameter and parameter
# type in the doc, see https://github.com/numpy/numpydoc/issues/215. The bug
# has been fixed in sphinx (https://github.com/sphinx-doc/sphinx/pull/5976) but
# through a change in sphinx basic.css except rtd_theme does not use basic.css.
# In an ideal world, this would get fixed in this PR:
# https://github.com/readthedocs/sphinx_rtd_theme/pull/747/files
def setup(app):
    app.add_stylesheet("basic.css")

[agjohnson]

The fix in #747 is probably not the optimal solution, we'd rather repair our CSS rulesets.

Can you clarify which domain this is using so that we can reproduce?

[lesteve]

Can you clarify which domain this is using so that we can reproduce?

Not sure what you mean by "which domain" but here is a way to reproduce:

conda create -n test-rtd -y -c conda-forge dask-jobqueue sphinx numpydoc -y
conda activate test-rtd
pip install dask_sphinx_theme
git clone https://github.com/dask/dask-jobqueue
# Goes back to an older version where we did not roll out our own fix
git checkout 0.6.1
cd dask-jobqueue/docs
make html

If you open _build/html/generated/dask_jobqueue.SGECluster.html in your browser, you'll notice the problem in the snapshot below (it looks like the parameter is called queuestr rather than queue which is of type str):

[agjohnson]

The domain is the sphinx domain:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html

Which language are you documenting? Python?

I'm not sure why the display is combined there. I probably won't have time to dig into your documentation to debug. You can help by providing the generated source reST that produced the above output so that we can create a test case in our docs if there isn't one already.

[fladd]

As far as I am concerned the most problematic thing by far is the lack of spacing between the parameter name and the parameter type. This has lead confusion for our users. For example, in the top post example, people would try to use morphologystr as parameter, rather than morphology.

The spacing issue has been reported in #746 and there is an associated PR #747 that will fix it. Unfortunately this PR does not seem to have received too much attention. I am guessing part of the reason is because it is a wide-reaching change.

For my project, html4_writer = True was not fixing this spacing issue. The simplest fix I found was dask/dask-jobqueue#301, i.e. add this in conf.py:

# Temporary work-around for spacing problem between parameter and parameter
# type in the doc, see https://github.com/numpy/numpydoc/issues/215. The bug
# has been fixed in sphinx (https://github.com/sphinx-doc/sphinx/pull/5976) but
# through a change in sphinx basic.css except rtd_theme does not use basic.css.
# In an ideal world, this would get fixed in this PR:
# https://github.com/readthedocs/sphinx_rtd_theme/pull/747/files
def setup(app):
    app.add_stylesheet("basic.css")

This does not work for me unfortunately.

[lesteve]

Which language are you documenting? Python?

Yes Python.

I'm not sure why the display is combined there. I probably won't have time to dig into your documentation to debug

As someone involved in the maintenance of open-source projects, at least one of them reasonably popular, I fully sympathise with this. My feeling though is that the root cause of the problem is understood and that a fix at the CSS level would be to add this (diff from sphinx-doc/sphinx#5976).

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

Is there a chance this fix gets added to #838 (I am afraid that my web skills are limited and I don't know sass at all ...)?

I agree that some comments have been scattered across separate issues, so that this is not very easy to follow. Let me try to summarize:

• for sphinx 2.0 HTML5Writer is the default and use CSS for the delimiter between parameter name and parameter type, see Colons missing between parameter names and types in API docs  sphinx-doc/sphinx#6400 (comment)
• a similar sphinx bug has been reported in BUG: numpydoc + autosumarry broken sphinx-doc/sphinx#5959 the sphinx CSS fix has been done in basic.css_t see Fix #5959: classifier delimiter is not shown sphinx-doc/sphinx#5976
• from what I understand from Inherent sphinx base css #747, reusing sphinx basic.css is not acceptable from sphinx_rtd_theme. You'd rather fix the Sphinx 2.0 issues in sphinx_rtd_theme rather than reuse sphinx basic.css.

[fladd]

How to get this grey columnar box behind "Parameters:"? This is not showing for me at all.

[agjohnson]

Ah thanks @lesteve! That's helpful. I'll add it to our list of Sphinx 2 compatibility fixes. That does indeed look like the fix we need to add.

[gdementen]

FWIW, using:

def setup(app):
    app.add_stylesheet("basic.css")

fixed the original issue for me BUT introduced other problems (alignment in some tables).
On the other hand, adding just

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

to a _static/custom.css file (and activating it by adding these lines to my conf.py) seems to work without negative side effect:

html_static_path = ['_static']
html_css_files = [
    'custom.css',
]

[agjohnson]

0.5.0rc1 is release to PyPI and should contain fixes for this issue. Can anyone verify?

[OriolAbril]

I can confirm using 0.5.0rc1 fixed this issue. Thanks!

[agjohnson]

Great, I'll close this for now. I'm hoping to address some issues with a follow up rc release today and we should move pretty quick towards a full release after that.

[ZhengRui]

@fladd Were you able to get the gray column box behind Parameters #766 (comment)? I have sphinx 3.2.0, sphinx-rtd-theme 0.5.0 installed, still for field list like Parameters, Returns it is rendered with in <table class="docutils field-list"></table>, instead of <dl></dl>. I am very confused if this is an issue of sphinx or the issue of sphinx-rtd-theme. According to edgi-govdata-archiving/web-monitoring-processing#468 (comment) , field list should be rendered with-in <dl></dl> for sphinx 2 above.

I want to achieve this style as show in sphinx-rtd-theme documentation page:

But what I have is like this:

@agjohnson, @fladd , Can you provide any insights on what could be wrong on my settings? Thanks 🙏

[ZhengRui]

Finally I am able to achieve same appearance by using this _static/custom.css

.rst-content dl:not(.docutils) dt:first-child {
  margin-top: 0;
}

.rst-content dl:not(.docutils) dl dt {
    margin-bottom: 4px;
    border: none;
    border-left: solid 3px #ccc;
    background: #f0f0f0;
    color: #555;
}

.rst-content dl table,
.rst-content dl ul,
.rst-content dl ol,
.rst-content dl p {
    margin-bottom: 8px !important;
}

.rst-content dl:not(.docutils) dt {
    display: table;
    margin: 6px 0;
    font-size: 90%;
    line-height: normal;
    background: #e7f2fa;
    color: #2980B9;
    border-top: solid 3px #6ab0de;
    padding: 6px;
    position: relative;
}

html.writer-html5 .rst-content dl.field-list {
    display: initial;
}

html.writer-html5 .rst-content dl.field-list>dd,
html.writer-html5 .rst-content dl.field-list>dt {
    margin-bottom: 4px;
    padding-left: 6px;
}

p {
    line-height: 20px;
    font-size: 14px;
}

html.writer-html5 .rst-content dl.field-list>dt:after {
    content: initial;
}

in conf.py add

html_css_files = [
    'custom.css'
]

Also I found the reason why field lists like Parameters rendered within <table class="docutils field-list"></table> is because I added html4_writer=True. Without adding it, it is rendered within <dl></dl>, and with the above css settings, it achieves same appearance as in the documentation.