sphinx
sphinx copied to clipboard
Missing HTML `<em>`, `</em>` tags when explicitly defining docstring types using domains like `:class:`, `:obj:`, and others
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.
- 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.
- 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.