Substitution messages in rst_epilog gets output in every POT files instead of only when used

[alvinhochun]

Describe the bug

The gettext build in Sphinx 4.0 outputs excessively unused messages to all the POT templates, as opposed to only when used in the page as in Sphinx 3.

How to Reproduce

$ # Clone https://invent.kde.org/documentation/docs-krita-org/-/tree/krita/4.3
$ git clone https://invent.kde.org/documentation/docs-krita-org.git -b krita/4.3
$ cd docs-krita-org
$ python3 -m venv .venv_sphinx3
$ . .venv_sphinx3/bin/activate
$ pip install sphinx==3.4.3
$ make gettext
$ # Check `404.pot` to see no messages from rst_epilog
$ grep rst_epilog _build/gettext/404.pot
$ # Check total occurences of rst_epilog
$ grep -r --include '*.pot' rst_epilog _build/gettext/ | wc -l
$ deactivate
$ rm _build/ -rf
$ python3 -m venv .venv_sphinx4
$ . .venv_sphinx4/bin/activate
$ pip install sphinx==4.0.3
$ make gettext
$ # Check `404.pot` to see plenty of messages from rst_epilog
$ grep rst_epilog _build/gettext/404.pot
$ # Check total occurences of rst_epilog
$ grep -r --include '*.pot' rst_epilog _build/gettext/ | wc -l
$ deactivate

Expected behavior

rst_epilog messages should not be duplicated in every POT files even when it is unused in the page.

Your project

https://invent.kde.org/documentation/docs-krita-org/-/tree/krita/4.3

Screenshots

No response

OS

Linux

Python version

3.9

Sphinx version

4.0.3

Sphinx extensions

No response

Extra tools

No response

Additional context

No response

[tk0miya]

Understandable.

At present, rst_prolog and rst_epilog are merged into each document before the parsing process. So Sphinx document processors (parsers, transforms, builders and so on) do not know the target document is consists of multiple sources. To make them separated, we need to change the structure of our components and its data structures.

[alvinhochun]

Thanks for the reply. Matt I ask what changes between 3.4.3 and 4.0.3 regarding the handling of rst_prolog and rst_epilog that caused this difference in behaviour?

[alvinhochun]

Hi @tk0miya, I just did a git bisect and it pointed to ebc3c68b78d5cf51f9aa49ca38dd371b7c204cd8 being the commit which caused the change in behaviour. Does this make sense to you?

[tk0miya]

Thank you for your investigation. I understand what is happened. And I think ebc3c68 is a correct fix. I think the behavior before 3.4.3 was incorrect because messages inside substitutions are not translatable.