[3.15] gh-151949: Fix Sphinx reference warnings in Doc/library/lzma.rst (GH-153878)

[miss-islington]

The lzma module constants (FORMAT_, CHECK_, PRESET_, FILTER_, MODE_*
and MF_*) were referenced with the :const: role throughout the module
documentation but were never defined as reference targets, producing
"reference target not found" warnings under nitpicky mode.

Document these public constants with .. data:: directives, following the
convention used by the signal, socket and ssl modules, so the existing
references resolve. The now-redundant inline descriptions of the format
and check constants are condensed into linked references.
(cherry picked from commit 1530b38)

Co-authored-by: Vyron Vasileiadis hi@fedonman.com

• Issue: Fix all Sphinx reference warnings in Doc/library/lzma.rst #151949

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33708909 | 📁 Comparing a75bf71 against main (1604043)

  🔍 Preview build  

307 files changed · + 1 added · ± 302 modified · - 4 deleted

+ Added

• library/asyncio-policy.html

± Modified

• glossary.html
• index.html
• py-modindex.html
• c-api/apiabiversion.html
• c-api/coro.html
• c-api/exceptions.html
• c-api/gen.html
• c-api/init_config.html
• c-api/interp-lifecycle.html
• c-api/module.html
• and 292 more...

- Deleted

• deprecations/pending-removal-in-3.21.html
• library/tkinter.fontchooser.html
• library/tkinter.systray.html
• whatsnew/3.16.html

[tomasr8]

@fedonman Looks like there are some extra warnings on the backports, could you take a look?

[fedonman]

The docs build fails here because this backport removes Doc/library/lzma.rst from Doc/tools/.nitignore, but six BCJ filter references in that file are still unresolved on this branch: FILTER_X86, FILTER_IA64, FILTER_ARM, FILTER_ARMTHUMB, FILTER_POWERPC and FILTER_SPARC.

On main those names carry a leading !, which tells Sphinx to render them as plain text and skip the reference lookup. That prefix came from GH-115989 (the ARM64 and RISCV filters), which was never backported, so this branch still has the plain references.

Adding the same ! prefix to those six lines clears the warnings. I don't have push access to this branch, so a core dev would need to apply it:

 * Branch-Call-Jump (BCJ) filters:

-  * :const:`FILTER_X86`
-  * :const:`FILTER_IA64`
-  * :const:`FILTER_ARM`
-  * :const:`FILTER_ARMTHUMB`
-  * :const:`FILTER_POWERPC`
-  * :const:`FILTER_SPARC`
+  * :const:`!FILTER_X86`
+  * :const:`!FILTER_IA64`
+  * :const:`!FILTER_ARM`
+  * :const:`!FILTER_ARMTHUMB`
+  * :const:`!FILTER_POWERPC`
+  * :const:`!FILTER_SPARC`

I checked with a nitpicky docs build that this clears all the lzma.rst warnings.

[fedonman]

@tomasr8 As far as I know, I can't commit/push to this branch as I am not a core dev. I commented the solution.

[tomasr8]

Thanks for looking into it! If you want, you can create a separate backport PR with the fixes and I'll close this one. Otherwise I'll fix the backports in the following days :)

[hugovk]

I pushed the fixes, thanks for investigating!