https://github.com/scarletcafe/sphinx-napoleon-gettext-bug
https://github.com/scarletcafe/sphinx-napoleon-gettext-bug
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/scarletcafe/sphinx-napoleon-gettext-bug
- Owner: scarletcafe
- License: mit
- Created: 2022-04-09T16:04:00.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2022-04-09T16:15:52.000Z (about 3 years ago)
- Last Synced: 2025-03-01T22:28:10.823Z (4 months ago)
- Language: Python
- Size: 8.79 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Sphinx gettext bug with napoleon
=================================
This repo demonstrates a bug with gettext+napoleon on Sphinx.
When a directive is included within parameter/return signatures that get processed by napoleon, it confuses gettext and makes the result untranslatable.
Running
```bash
cd docs
PYTHONPATH=$(cd .. && pwd) make html
```
or
```powershell
$env:PYTHONPATH="$(pwd)"; docs/make html
```
produces .pot files that contain these, derived with autodoc from the [module](foobar/__init__.py):
```
#: ../../../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 both the 'unclean' and 'clean' versions both being present, only the first (unclean) version actually gets used, making these strings untranslatable as anything other than removing the directives either results in them appearing in the resulting document 'as is' (e.g. not parsed), or Sphinx kicking out an error.