sphinx-doc / sphinx-doc/sphinx

RST directives inside Napoleon-processed blocks are not handled correctly by gettext

Open
#10,334 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:gettext extensions:napoleon i18n type:bug
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.

image

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.