Weird numpydoc-generated parameter tables after upgrade to v0.5.0

[lukelbd]

Problem

I use napoleon and autosummary for numpydoc-style automatic documentation generation. All the pages in my "API Reference" section switched from the "Expected Result" to the "Actual Result" after upgrading to version 0.5.0 (see below).

For details, you can also compare this older version of my docs on readthedocs.io, generated with sphinx_rtd_theme 0.4.3, with the stable version, generated with 0.5.0. Note the results are the same when I generate the documentation locally.

Expected Result

Normal numpydoc-style parameter tables:

Actual Result

Weird tables, with parameter lists bleeding into the margin and a two-column table rather than bullet points for parameter names:

Reproducible Project

Documentation tree: https://github.com/lukelbd/proplot/tree/master/docs

Relevant contents of conf.py:

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
    'IPython.sphinxext.ipython_console_highlighting',
    'IPython.sphinxext.ipython_directive',  # for ipython highlighting
    'sphinx.ext.autodoc',  # include documentation from docstrings
    'sphinx.ext.doctest',  # >>> examples
    'sphinx.ext.extlinks',  # for :pr:, :issue:, :commit:
    'sphinx.ext.autosectionlabel',  # use :ref:`Heading` for any heading
    'sphinx.ext.todo',  # Todo headers and todo:: directives
    'sphinx.ext.mathjax',  # LaTeX style math
    'sphinx.ext.viewcode',  # view code links
    'sphinx.ext.napoleon',  # for NumPy style docstrings
    'sphinx.ext.intersphinx',  # external links
    'sphinx.ext.autosummary',  # autosummary directive
    'sphinxext.custom_roles',  # local extension
    'sphinx_copybutton',
    'sphinx_automodapi.automodapi',  # see: https://github.com/lukelbd/sphinx-automodapi/tree/proplot-mods # noqa
    'nbsphinx',
]

# Napoleon options
# See: http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
napoleon_use_ivar = False
napoleon_use_param = False
napoleon_use_keyword = False
napoleon_use_rtype = False
napoleon_numpy_docstring = True
napoleon_google_docstring = False
napoleon_include_init_with_doc = False  # move init doc to 'class' doc

# Rtd theme
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
    'logo_only': True,
    'display_version': False,
    'collapse_navigation': True,
    'navigation_depth': 4,
    'prev_next_buttons_location': 'bottom',  # top and bottom
}

Environment Info

• Python Version: 3.6
• Sphinx Version: 3.1.1
• RTD Theme Version: 0.5.0

[agjohnson]

@lukelbd Thanks for the report. This might be a theme bug, however I haven't seen this replicated in any of other autodoc usage. I see you're doing something custom on your docs, using an extension[1] to generate the autodoc output. Could you verify that this is not the source of the problem first?

1: https://github.com/lukelbd/proplot/blame/master/docs/api.rst#L10

[lukelbd]

I see you're doing something custom on your docs, using an extension[1] to generate the autodoc output. Could you verify that this is not the source of the problem first?

Sure I'll check when I get the chance. I guess sphinx-automodapi could be incompatible with v0.5

[lukelbd]

Created a minimal branch without any custom templates or style overrides, and without the sphinx-automodapi plugin -- results are the same (btw all sphinx-automodapi does is generate autosummary directives to catalogue all the public functions/classes/methods). The issue seems to be that the headers/parameters are put in 2 separate columns:

This causes margin bleed only when there is a too-wide table in the parameters section (in version 0.4.3, you can horizontally scroll this table):

But it still looks cramped even without the margin bleed (those Parameters/Other Parameters should be section headers). Version 0.5.0:

versus version 0.4.3:

I checked the relevant HTML code and it's the same for both versions:

<dl class="field-list">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul>
<li><p><strong>array</strong> (<em>2d array-like of int, optional</em>) – Array specifying complex grid of subplots. Think of
this array as a “picture” of your figure. For example, the array...

[lukelbd]

You should be able to reproduce this by cloning my branch, creating a conda environment with docs/environment.yml, and running make html inside the docs folder.

[agjohnson]

Okay, so the second image is correct, the third is a bug in Sphinx 3 + sphinx_rtd_theme == 0.4.3. If you use html4_writer = True with sphinx_rtd_theme 0.4.3, you should get something close to the second image. I've suggested something like the third image for an improvement to the listing, but for now, 0.5.0 approximates what 0.4.3 + html4 writer.

The first image is definitely a bug of sorts. The nested table is ultimately the cause here, though it shouldn't cause the entire display to expand like you're seeing. I should be able to add a test case that easily reproduced this -- and wide block content will end up triggering this sort of display.

I'd be curious what the behavior of sphinx_rtd_theme 0.4.3 + html4_writer = True is. My guess is it's something close to, but not as heinous as the first image.