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