sphinx icon indicating copy to clipboard operation
sphinx copied to clipboard

Missing HTML `<em>`, `</em>` tags when explicitly defining docstring types using domains like `:class:`, `:obj:`, and others

Open ProGamerGov opened this issue 3 years ago • 0 comments

Describe the bug

When manually adding :obj: or :class: to the docstring types, they are no longer formatted as italics. Somehow Sphinx is able to implicitly hyperlink some of the types and italicize them when they are not manually specified with :obj: or :class:.

I think that the correct output would see the <em>, </em> tags for emphasis being created, but there appears to be no way to ensure that they do. I can't manually ensure that they're added by using asterisks either (ex: *type*) as Sphinx can't handle that sort of nested formatting (I think?).

How to Reproduce

# conf.py
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
]

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
}
def my_func(show_progress: bool = True) -> bool:
    """
    Args:

        show_progress (bool, optional): Displays the progress of computation.
    """
    return show_progress

This is an example of HTML code generated by Sphinx without explicitly defining the types:

<li><p><strong>show_progress</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.10)"><em>bool</em></a><em>, </em><em>optional</em>) – Displays the progress of computation.

progress_show1

  • Notice how everything inside the brackets is italicized.

And this is the same HTML, except for the bool variable being explicitly wrapped in :class:bool``:

def my_func(show_progress: bool = True) -> bool:
    """
    Args:

        show_progress (`:class:`bool`, optional): Displays the progress of computation.
    """
    return show_progress
<li><p><strong>show_progress</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.10)"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a>, optional) – Displays the progress of computation.

progress_no_italics

  • Notice how nothing inside the brackets is italicized.

The <em> and </em> tags are missing in the second example for some reason.

Expected behavior

There should be some way to ensure that the <em> HTML tags are still created when explicitly defining the types that should be hyperlinked.

Your project

N/A, but the project I discovered this issue for is pytorch/captum

Screenshots

No response

OS

Ubuntu 18.04.5 LTS (x86_64)

Python version

3.7.13 (default, Apr 24 2022, 01:04:09) [GCC 7.5.0] (64-bit runtime)

Sphinx version

Sphinx v4.3.2, Sphinx v5.x

Sphinx extensions

sphinx.ext.autodoc, sphinx.ext.napoleon, sphinx.ext.intersphinx

Extra tools

No response

Additional context

The reason that I am trying to explicitly define the types inside the docstring type brackets, is that the format type1 of type2 does not work. Edit: This seems like it'll be solved in an upcoming Sphinx release.

ProGamerGov avatar Jul 31 '22 15:07 ProGamerGov