substitution_definition nodes are missing from the doctree

[brechtm]

Since PR #4827 all substitution_definition nodes are removed from the docutils doctree. Reasoning behind this was that this node was not being used by any builders included with Sphinx. However, third-party builders might make use of them. rinohtype, for example parses them to be able to reference the definitions in the a document template.

I think it would be better for the document tree that Sphinx passes to builders to match the standard docutils document tree as much as possible. A single builder (LaTeX in this case) having an issue with the document tree shouldn't be a reason to change the doctree for all builders.

I propose making the ´SubstitutionsDefinitionsRemover´ transform local to the LaTeX builder, as was originally intended. I can provide a PR if you wish.

Please also consider third-party builders when making changes like this (e.g. doctree) in the future. Thanks!

[tk0miya]

I don't think this is a bug. But I can accept the change. Could you send a PR please?

BTW, how does rinohtype use such node? I can't imagine how it works. On the writing phase, there are no substitution_reference nodes. Is it enough to build some document?

[brechtm]

I had a go at reverting to the behavior of only removing the substitition definition nodes for the LaTeX builder (PR #4827) here: brechtm@dfa1976. Unfortunately, the test_latex_show_urls_footnote_and_substitutions test case still fails with these changes in place.

I assume the LaTeX builder has been changed since #4827 was merged, causing the footnote numbers to be determined earlier? I haven't been able to find the cause for this. I have tried calling apply_transforms earlier, to no avail. Perhaps @jfbu can point me in the right direction?

I believe #4293 will also be fixed if we undo removal of the substitution definition nodes.

PS. rinohtype allows referencing substitutions outside of the realm of the reStructuredText input files, e.g. in a document template. This can be used to put customized text in a page header or footer, for example.

[brechtm]

The changes that cause brechtm@dfa1976 not to work have been applied somewhere between v2.0.1 and v2.1.0. With the help of git bisect, I've determined b5959ca to be the culprit.

[brechtm]

I think I've found the correct way to fix this. See PR #8183.