sphinx-doc / sphinx-doc/sphinx
RST directives inside Napoleon-processed blocks are not handled correctly by gettext
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
Consider this function:
def documented_function(small: bool = False):
"""
Use this when you want to look at a picture of a duck.
Parameters
-----------
small: :class:`bool`
Whether the duck should be small or not.
.. warning::
This duck is very small.
Returns
--------
str
A nice `picture of a duck`__.
.. _picture_of_a_duck: https://upload.wikimedia.org/wikipedia/commons/5/51/Mandarin.duck.arp.jpg
__ picture_of_a_duck_
"""
...
When directives .. warning:: and .. _picture_of_a_duck: are outside of the Parameters/Returns blocks, they get handled by gettext as normal (as in, the directives themselves are not included, only the respective text is).
However, running make gettext results in this in the .pot files:
#: ../../../foobar/__init__.py:docstring of foobar.documented_function:3
msgid "Whether the duck should be small or not. .. warning:: This duck is very small."
msgstr ""
#: ../../../foobar/__init__.py:docstring of foobar.documented_function:3
msgid "Whether the duck should be small or not."
msgstr ""
#: ../../../foobar/__init__.py:docstring of foobar.documented_function:6
msgid "This duck is very small."
msgstr ""
#: ../../../foobar/__init__.py:docstring of foobar.documented_function:9
msgid "A nice `picture of a duck`__. .. _picture_of_a_duck: https://upload.wikimedia.org/wikipedia/commons/5/51/Mandarin.duck.arp.jpg __ picture_of_a_duck_"
msgstr ""
#: ../../../foobar/__init__.py:docstring of foobar.documented_function:9
msgid "A nice `picture of a duck`__."
msgstr ""
Despite the correct handling being included afterwards, any point at which this occurs includes a wrongly-"folded" version at the beginning, and this is the version Sphinx ends up actually using.
This version is not translatable, as changing into the correct formatting causes Sphinx to error from formatting/indentation complaints, and leaving them as is results in them being presented "as is" in the document (unparsed plaintext).
How to Reproduce
$ git clone https://github.com/Gorialis/sphinx-napoleon-gettext-bug
$ cd sphinx-napoleon-gettext-bug
$ pip install -r requirements.txt
$ cd docs
$ PYTHONPATH=$(cd .. && pwd) make gettext
Expected behavior
Only the individual parts without the directives should be included, so they do not take priority over the 'correct' versions that follow such that the docstrings can be correctly translated.
Your project
https://github.com/Gorialis/sphinx-napoleon-gettext-bug
Screenshots
It is worth noting that despite it being handled by gettext incorrectly, this directive-in-parameter format IS accepted by Sphinx's html builder itself. It just breaks the translated versions.

OS
Windows 10 Pro 21H2 19044.1586 / Arch Linux on kernel 5.16.2
Python version
3.10.2
Sphinx version
4.5.0
Sphinx extensions
sphinx.ext.autodoc, sphinx.ext.napoleon
Extra tools
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Run the provided reproduction with make gettext and inspect the generated .pot entries for the Napoleon-processed docstring. Start at the interaction between sphinx.ext.napoleon, autodoc, and gettext, then verify that directive text inside Parameters and Returns blocks is excluded while the individual translatable text remains. Done means the reproduction no longer emits the incorrectly folded messages.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, localization
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100