Gettext builder cannot extract 'option' directive

hwhsu1231 commented 3 months ago

Describe the bug

Hello, Sphinx Maintainance Team.

Recently, I tried to translate CMake Documentation with its .po files generated by Gettext builder. In CMake Documentation, we can see that there is a type of content derived from the Sphinx option directive. Take cmake's --graphviz=<file> as an example:

Corresponding .html link: --graphviz=<file>
Corresponding .rst link: --graphviz=<file>

If possible, I want to translate the <file> in the --graphviz=<file> as well. However, I found that even though I specify all the possible values in gettext_additional_targets when building with gettext builder:

-Dgettext_additional_targets=index,literal-block,doctest-block,raw,image

I still don't see the content of option directives being extracted into the generated cmake.1.pot.

What did I miss? Is this a bug? Or Is Sphinx's gettext builder designed to be unable to extract option directive? Or is it just not able to do it currently, and is required a feature request?

How to Reproduce

Run the following commands in order:

git clone --depth=1 --branch=v3.28.4 https://github.com/Kitware/CMake.git
cd CMake
cmake -D SPHINX_HTML=ON -S Utilities/Sphinx -B Utilities/Sphinx/build
LANG=en_US.UTF-8 sphinx-build -b gettext -Dgettext_additional_targets=index,literal-block,doctest-block,raw,image -Dgettext_compact=0 -c Utilities/Sphinx/build Help Help/locale/pot
kate Help/locale/pot/manual/cmake.1.pot

Search --graphviz=<file> string in Kate (Ctrl+F).

Expected/Actual Result:

Expected Result: Find an entry with --graphviz=<file> in the cmake.1.pot.
Actual Result: Not found.

Environment Information

Platform:              linux; (Linux-6.5.0-35-generic-x86_64-with-glibc2.35)
Python version:        3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.16.1

Sphinx extensions

No response

Additional context

Full log of How to Reproduce

Click to expand the full log

```bash hwhsu1231@vb-kubuntu:~/Repo/testing$ git clone --depth=1 --branch=v3.28.4 https://github.com/Kitware/CMake.git Cloning into 'CMake'... remote: Enumerating objects: 21228, done. remote: Counting objects: 100% (21228/21228), done. remote: Compressing objects: 100% (15454/15454), done. remote: Total 21228 (delta 4458), reused 14380 (delta 3547), pack-reused 0 Receiving objects: 100% (21228/21228), 13.11 MiB | 7.55 MiB/s, done. Resolving deltas: 100% (4458/4458), done. Note: switching to 'b5602e7254c8ce4a6f732c017d784cd80559e5aa'. You are in 'detached HEAD' state. You can look around, make experimental changes and commit them, and you can discard any commits you make in this state without impacting any branches by switching back to a branch. If you want to create a new branch to retain commits you create, you may do so (now or later) by using -c with the switch command. Example: git switch -c Or undo this operation with: git switch - Turn off this advice by setting config variable advice.detachedHead to false hwhsu1231@vb-kubuntu:~/Repo/testing$ cd CMake hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ cmake -D SPHINX_HTML=ON -S Utilities/Sphinx -B Utilities/Sphinx/build -- Configuring done (0.3s) -- Generating done (0.0s) -- Build files have been written to: /home/hwhsu1231/Repo/testing/CMake/Utilities/Sphinx/build hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ LANG=en_US.UTF-8 sphinx-build -b gettext -Dgettext_additional_targets=index,literal-block,doctest-block,raw,image -Dgettext_compact=0 -c Utilities/Sphinx/build Help Help/locale/pot Running Sphinx v7.2.6 making output directory... done building [gettext]: targets for 1 template files reading templates... [100%] /home/hwhsu1231/Repo/testing/CMake/Utilities/Sphinx/templates/layout.html building [gettext]: targets for 1997 source files that are out of date updating environment: [new config] 1997 added, 0 changed, 0 removed reading sources... [100%] variable/XCODE_VERSION looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done copying assets... done writing output... [100%] variable/XCODE_VERSION writing message catalogs... [100%] variable/XCODE_VERSION build succeeded. The message catalogs are in Help/locale/pot. hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ kate Help/locale/pot/manual/cmake.1.pot hwhsu1231@vb-kubuntu:~/Repo/testing/CMake$ ```

n-peugnet commented 3 months ago

What did I miss? Is this a bug? Or Is Sphinx's gettext builder designed to be unable to extract option directive? Or is it just not able to do it currently, and is required a feature request?

Sphinx's gettext builder is currently explicitly designed to ignore certain strings by default, such as code-blocks, or the option directive. Though some have been added as optional additional targets, it is usually useful to ignore them as these are strings that are likely not to be changed by translations.

The option directive simply hasn't been yet added as a possible additional target. But it would not be trivial to add as it is also a cross-reference target, so it would be quite difficult to make it work correctly if the option name is changed in the translations.

hwhsu1231 commented 3 months ago

Hello, @n-peugnet

The option directive simply hasn't been yet added as a possible additional target. But it would not be trivial to add as it is also a cross-reference target, so it would be quite difficult to make it work correctly if the option name is changed in the translations.

What about translating the entry which cross-references the option directive with the following form:

# Source (msgid)
:option:`--graphviz=<file>`

# Translation (msgstr)
:option:`--graphviz=<檔案> <--graphviz=<file>>`

Just like the way CMake Documentation did in its cmake.1.rst

:manual:`CMake Presets <cmake-presets(7)>`

Is it possible to do so?

n-peugnet commented 3 months ago

What about translating the entry which cross-references the option directive with the following form:
# Source (msgid)
:option:`--graphviz=<file>`

# Translation (msgstr)
:option:`--graphviz=<檔案> <--graphviz=<file>>`

Translating the option role and adding an explicit target should already possible. You were initially talking about the option directive.

Maybe a simple way to do it would be to only extract the option's example value (=<file> in your initial example), as it seems like is is already treated differently from the rest, and changing it should not affect the cross-referencing (it is not mandatory in the option role). But I didn't check the code yet, so not sure how complicated it would be and if it really is a good idea.

Anyway, this should be tagged as a feature request as this is not a bug, but I don't have the permissions to change the tags myself.

jayaddison commented 2 months ago

(issue labels updated; let me know if those seem accurate/inaccurate)

sphinx-doc / sphinx