Sphinx: Change in autodoc html rendering in 2.x

Created on 11 Jun 2019 · 2Comments · Source: sphinx-doc/sphinx

Describe the bug

The NumpyDoc-style docstrings use field lists for the parameter listing and then definition lists for each parameter. Eg a docstring with this section (from here):

        Return DataFrame with duplicate rows removed, optionally only
        considering certain columns. Indexes, including time indexes
        are ignored.

        Parameters
        ----------
        subset : column label or sequence of labels, optional
            Only consider certain columns for identifying duplicates, by
            default use all of the columns
        keep : {'first', 'last', False}, default 'first'
            - ``first`` : Drop duplicates except for the first occurrence.
            - ``last`` : Drop duplicates except for the last occurrence.
            - False : Drop all duplicates.
        inplace : boolean, default False
            Whether to drop duplicates in place or to return a copy

        Returns
        -------
        DataFrame

is converted by numpydoc to:

Return DataFrame with duplicate rows removed, optionally only
considering certain columns. Indexes, including time indexes
are ignored.


:Parameters:

    **subset** : column label or sequence of labels, optional
        Only consider certain columns for identifying duplicates, by
        default use all of the columns

    **keep** : {'first', 'last', False}, default 'first'
        - ``first`` : Drop duplicates except for the first occurrence.
        - ``last`` : Drop duplicates except for the last occurrence.
        - False : Drop all duplicates.

    **inplace** : boolean, default False
        Whether to drop duplicates in place or to return a copy

:Returns:

    DataFrame
        ..

The above is a field list where each parameter is a definition list.

In sphinx 1.8.5, this gets translated to the following html:

<table class="docutils field-list" frame="void" rules="none">
<colgroup><col class="field-name">
<col class="field-body">
</colgroup><tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><dl class="first docutils">
<dt><strong>subset</strong> <span class="classifier-delimiter">:</span> <span class="classifier">column label or sequence of labels, optional</span></dt>
<dd><p class="first last">Only consider certain columns for identifying duplicates, by
default use all of the columns</p>
</dd>
<dt><strong>keep</strong> <span class="classifier-delimiter">:</span> <span class="classifier">{‘first’, ‘last’, False}, default ‘first’</span></dt>
<dd><ul class="first last simple">
<li><code class="docutils literal notranslate"><span class="pre">first</span></code> : Drop duplicates except for the first occurrence.</li>
<li><code class="docutils literal notranslate"><span class="pre">last</span></code> : Drop duplicates except for the last occurrence.</li>
<li>False : Drop all duplicates.</li>
</ul>
</dd>
<dt><strong>inplace</strong> <span class="classifier-delimiter">:</span> <span class="classifier">boolean, default False</span></dt>
<dd><p class="first last">Whether to drop duplicates in place or to return a copy</p>
</dd>
</dl>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><dl class="first last docutils">
<dt><strong>deduplicated</strong> <span class="classifier-delimiter">:</span> <span class="classifier">DataFrame</span></dt>
<dd></dd>
</dl>
</td>
</tr>
</tbody>
</table>

where we have a "docutils field-list" table (with a field-name and field-body column), and the html definition lists (<dl>) for the parameter section.

But on sphinx master (and starting from sphinx 2.0 I think), it gives:

<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><dl class="simple">
<dt><strong>subset</strong><span class="classifier">column label or sequence of labels, optional</span></dt><dd><p>Only consider certain columns for identifying duplicates, by
default use all of the columns</p>
</dd>
<dt><strong>keep</strong><span class="classifier">{‘first’, ‘last’, False}, default ‘first’</span></dt><dd><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">first</span></code> : Drop duplicates except for the first occurrence.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">last</span></code> : Drop duplicates except for the last occurrence.</p></li>
<li><p>False : Drop all duplicates.</p></li>
</ul>
</dd>
<dt><strong>inplace</strong><span class="classifier">boolean, default False</span></dt><dd><p>Whether to drop duplicates in place or to return a copy</p>
</dd>
</dl>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><dl class="simple">
<dt><strong>deduplicated</strong><span class="classifier">DataFrame</span></dt><dd></dd>
</dl>
</dd>
</dl>

where the outer docutils field-list table is replaced with a definition list as well.

This change breaks the styling of a number of projects that use numpydoc that were specialized for this docutils table. See eg https://github.com/numpy/numpydoc/issues/215 and the linked issues.

Since it is a rather big change, I suppose this was intentional? (although I didn't find anything in the changes log)
But what was the reason for the change? The new html is a lot harder to style.

To Reproduce

Steps to reproduce the behavior (I have a test project in https://github.com/jorisvandenbossche/sphinx-test in the test-autodoc subdir):

$ git clone https://github.com/jorisvandenbossche/sphinx-test
$ cd sphinx-test/test-autodoc
$ pip install numpydoc
$ make html
$ # open _build/html/index.html

Additional context