Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extra linebreak when autodoc-documented parameter has multi-paragraph output #2098

Open
cmarqu opened this issue Jan 19, 2025 · 2 comments
Open

Comments

@cmarqu
Copy link
Contributor

cmarqu commented Jan 19, 2025

I noticed that when autodoc produces multi-paragraph output in HTML, I get an extra linebreak between the parameter name and the description.
In the following example (which is only indirectly using PST via SBT), stacklevel looks fine, but name has the extra linebreak:

Image

When I run sphinx-build with -vvv, I'm getting

[autodoc] output:
[...]
      :param stacklevel: Which stack level to add the generated tests to. This can be used to make a custom TestFactory wrapper.
      :param name: Passed as ``name`` argument to :func:`cocotb.test`.

                   .. versionadded:: 2.0
[...]

and the resulting HTML is

<li><p><strong>stacklevel</strong> (<em>int</em>) – Which stack level to add the generated tests to. This can be used to make a custom TestFactory wrapper.</p></li>
<li><p><strong>name</strong> (<em>str</em><em> | </em><em>None</em>) – <p>Passed as <code class="docutils literal notranslate"><span class="pre">name</span></code> argument to <a class="reference internal" href="#cocotb.test" title="cocotb.test"><code class="xref py py-func docutils literal notranslate"><span class="pre">cocotb.test()</span></code></a>.</p>
<div class="versionadded">
<p><span class="versionmodified added">Added in version 2.0.</span></p>
</div>
</p></li>

There should be some CSS that removes the extra linebreak.


As a side note, my PR sphinx-themes/sphinx-themes.org#157 could be taken for https://github.com/pydata/pydata-sphinx-theme/tree/main/docs/examples/kitchen-sink and would then show the problem in pure PST.
The current code is not exercising this autodoc feature: https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/kitchen-sink/api.html

@cmarqu
Copy link
Contributor Author

cmarqu commented Jan 19, 2025

I forgot to mention, this is with both Sphinx 7.4.7 and 8.1.3, and also happens with sphinx-rtd-theme.

@cmarqu
Copy link
Contributor Author

cmarqu commented Jan 19, 2025

The CSS I have come up with so far is

dl.field-list.simple > dd > p,
dl.field-list.simple > dd > ul.simple > li > p {
    display: inline;
}

cmarqu added a commit to cocotb/cocotb that referenced this issue Jan 19, 2025
cmarqu added a commit to cocotb/cocotb that referenced this issue Jan 19, 2025
cmarqu added a commit to cocotb/cocotb that referenced this issue Jan 20, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant