Add gettext builder as target for Doc's Makefile

Idea and reasoning:

As some may know already, gettext Sphinx builder is used to extract strings from the docs and store them in message catalog templates (pot files).

Currently there is no straightforward make gettext command to generate pot files, so the language teams need to run commands like:

sphinx-build -b gettext -D gettext_compact=0 . locales/pot

or via make command using doc’s Makefile:

make build BUILDER=gettext SPHINXOPTS='-D gettext_compact=0'

(On a side note, the first command doesn’t generate ‘changelog.pot’.)

In my personal opinion, having a gettext target would simplify the process, reducing the complexity of the command construction and uniformizing the outputs. It would also be a small step to simplifying the setup for new teams.

NOTE: I brought up this topic to translation mailing list (private, need to be subscribed), but decided to post it here to for more visibility and more feedback.

Patch:

The following patch worked for me. I had to add the gettext target to Makefile and add Sphinx option gettext_compact to False in config.py, otherwise it would build the docs translated.

diff --git a/Doc/Makefile b/Doc/Makefile
index dd068c520a..dce7f7ab8a 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -140,6 +140,10 @@ pydoc-topics: build
        @echo "Building finished; now run this:" \
              "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py"
 
+.PHONY: gettext
+gettext: BUILDER = gettext
+gettext: build
+
 .PHONY: htmlview
 htmlview: html
        $(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/html/index.html'))"
diff --git a/Doc/conf.py b/Doc/conf.py
index 0e86de837d..47fb96fe1d 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -374,6 +374,8 @@
 # Split the index
 html_split_index = True
 
+# Split pot files one per reST file
+gettext_compact = False
 
 # Options for LaTeX output
 # ------------------------
1 Like

Sounds reasonable to me, would you like to open a PR?

1 Like

Done: docs: Add gettext target by rffontenelle · Pull Request #119006 · python/cpython · GitHub

1 Like

Should I add NEWS entry or not a big enough change? I assume not, after reading the related section in devguide.

1 Like