gh-101100: Fix Sphinx warnings in library/tarfile.rst

[hugovk]

Fix 23 warnings:

❯ SPHINXERRORHANDLING=-n PATH=./venv/bin:$PATH sphinx-build -b html -d buildDoctrees -j auto -n . build/html library/tarfile.rst 2>&1| grep WARNING | tee >(wc -l)Doc/library/tarfile.rst:115: WARNING: py:meth reference target not found: readDoc/library/tarfile.rst:115: WARNING: py:meth reference target not found: writeDoc/library/tarfile.rst:326: WARNING: py:attr reference target not found: nameDoc/library/tarfile.rst:361: WARNING: py:attr reference target not found: ~TarFile.errorlevelDoc/library/tarfile.rst:648: WARNING: py:meth reference target not found: !TarFile.getmemberDoc/library/tarfile.rst:648: WARNING: py:meth reference target not found: !TarFile.getmembersDoc/library/tarfile.rst:648: WARNING: py:meth reference target not found: TarInfo.replaceDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: REGTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: AREGTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: LNKTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: SYMTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: DIRTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: FIFOTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: CONTTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: CHRTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: BLKTYPEDoc/library/tarfile.rst:730: WARNING: py:const reference target not found: GNUTYPE_SPARSEDoc/library/tarfile.rst:740: WARNING: py:const reference target not found: LNKTYPEDoc/library/tarfile.rst:740: WARNING: py:const reference target not found: SYMTYPEDoc/library/tarfile.rst:819: WARNING: py:class reference target not found: TarinfoDoc/library/tarfile.rst:954: WARNING: py:const reference target not found: stat.S_IWGRP`|:const:`~stat.S_IWOTHDoc/library/tarfile.rst:979: WARNING: py:const reference target not found: stat.S_IRUSR`|:const:`~stat.S_IWUSRDoc/library/tarfile.rst:981: WARNING: py:const reference target not found: stat.S_IXGRP`|:const:`~stat.S_IXOTH 23

Involved adding docs for a number of constants, based on the comments from the source:

cpython/Lib/tarfile.py

Lines 87 to 99 in cfa25fe

	REGTYPE=b"0"# regular file
	AREGTYPE=b"\0"# regular file
	LNKTYPE=b"1"# link (inside tarfile)
	SYMTYPE=b"2"# symbolic link
	CHRTYPE=b"3"# character special device
	BLKTYPE=b"4"# block special device
	DIRTYPE=b"5"# directory
	FIFOTYPE=b"6"# fifo special device
	CONTTYPE=b"7"# contiguous file
	GNUTYPE_LONGNAME=b"L"# GNU tar longname
	GNUTYPE_LONGLINK=b"K"# GNU tar longlink
	GNUTYPE_SPARSE=b"S"# GNU tar sparse file

The order matches that in the source.

GNUTYPE_SPARSE is referenced in the docs (and caused a warning), GNUTYPE_LONGNAME and GNUTYPE_LONGLINK are not; I added all three to docs.

• Issue: Fix all Sphinx reference warnings in the documentation #101100

---

📚 Documentation preview 📚: https://cpython-previews--113237.org.readthedocs.build/en/113237/library/tarfile.html

[willingc]

Looks good @hugovk. Thanks for fixing the warnings.

I wasn't sure if the backslashes were strictly needed in rST but the rendered version looks good.

[willingc]

Are the backslashes necessary here?

[hugovk]

Yes, the original doesn't render properly, we get a reference warning, and the earlier mention doesn't link to it:

https://docs.python.org/3/library/tarfile.html#tarfile.TarInfo.pax_headers

With them it's rendered properly, and the reference works properly:

https://cpython-previews--113237.org.readthedocs.build/en/113237/library/tarfile.html#tarfile.TarInfo.replace

Alternatively, we can remove the backticks, and make it a long, single line.

[miss-islington-app]

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @hugovk, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker f428c4dafbfa2425ea056e7f2ed2ea45fa90be87 3.12 

[miss-islington-app]

Sorry, @hugovk, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker f428c4dafbfa2425ea056e7f2ed2ea45fa90be87 3.11 

[bedevere-app]

GH-113244 is a backport of this pull request to the 3.12 branch.

[bedevere-app]

GH-113245 is a backport of this pull request to the 3.11 branch.