Add gettext target to documentation's Makefile

[rffontenelle]

Feature or enhancement

Proposal:

As some may know already, Sphinx's gettext 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.

Having a gettext target would allow to simply run make gettext and have the pot files in build/gettext directory. See output:

$ make gettext
mkdir -p build
Building NEWS from Misc/NEWS.d with blurb
/home/rffontenelle/Projects/cpython/Doc/build/NEWS is already up to date
PATH=./venv/bin:$PATH sphinx-build -b gettext -d build/doctrees -j auto -W . build/gettext 
Running Sphinx v7.3.7
building [gettext]: targets for 7 template files
reading templates... [100%] /home/rffontenelle/Projects/cpython/Doc/tools/templates/search.html
building [gettext]: targets for 469 source files that are out of date
updating environment: [new config] 469 added, 0 changed, 0 removed
reading sources... [100%] using/unix .. whatsnew/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... done
writing output... [100%] whatsnew/index
writing message catalogs... [100%] whatsnew/index
build succeeded.

The message catalogs are in build/gettext.

$ ls build/gettext/
about.pot c-api copyright.pot extending glossary.pot installing license.pot sphinx.pot using
bugs.pot contents.pot distributing faq howto library reference tutorial whatsnew

$ find build/gettext/ -name '*.pot' | wc -l
470

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/add-gettext-builder-as-target-for-docs-makefile/53229

Linked PRs

• gh-119009: Add gettext target #119006
• [3.13] gh-119009: Add gettext target (GH-119006) #119074
• [3.12] gh-119009: Add gettext target (GH-119006) #119075