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

hugovk · 2023-12-17T19:09:41Z

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: read
Doc/library/tarfile.rst:115: WARNING: py:meth reference target not found: write
Doc/library/tarfile.rst:326: WARNING: py:attr reference target not found: name
Doc/library/tarfile.rst:361: WARNING: py:attr reference target not found: ~TarFile.errorlevel
Doc/library/tarfile.rst:648: WARNING: py:meth reference target not found: !TarFile.getmember
Doc/library/tarfile.rst:648: WARNING: py:meth reference target not found: !TarFile.getmembers
Doc/library/tarfile.rst:648: WARNING: py:meth reference target not found: TarInfo.replace
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: REGTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: AREGTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: LNKTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: SYMTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: DIRTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: FIFOTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: CONTTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: CHRTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: BLKTYPE
Doc/library/tarfile.rst:730: WARNING: py:const reference target not found: GNUTYPE_SPARSE
Doc/library/tarfile.rst:740: WARNING: py:const reference target not found: LNKTYPE
Doc/library/tarfile.rst:740: WARNING: py:const reference target not found: SYMTYPE
Doc/library/tarfile.rst:819: WARNING: py:class reference target not found: Tarinfo
Doc/library/tarfile.rst:954: WARNING: py:const reference target not found: stat.S_IWGRP`|:const:`~stat.S_IWOTH
Doc/library/tarfile.rst:979: WARNING: py:const reference target not found: stat.S_IRUSR`|:const:`~stat.S_IWUSR
Doc/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 · 2023-12-17T19:22:20Z

Doc/library/tarfile.rst

@@ -795,8 +840,8 @@ A ``TarInfo`` object has the following public data attributes:

   A dictionary containing key-value pairs of an associated pax extended header.

-.. method:: TarInfo.replace(name=..., mtime=..., mode=..., linkname=...,
-                            uid=..., gid=..., uname=..., gname=...,
+.. method:: TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., \


Are the backslashes necessary here?

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 · 2023-12-18T06:57:49Z

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

miss-islington-app · 2023-12-18T06:58:08Z

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 · 2023-12-18T06:58:32Z

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 · 2023-12-18T07:05:07Z

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

bedevere-app · 2023-12-18T07:06:59Z

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

…ythonGH-113237) Fix Sphinx warnings in library/tarfile.rst (cherry picked from commit f428c4d) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

…) (#113244)

…) (#113245)

…13237) Fix Sphinx warnings in library/tarfile.rst

Fix Sphinx warnings in library/tarfile.rst

fbcf959

hugovk requested a review from ethanfurman as a code owner December 17, 2023 19:09

bedevere-app bot added the awaiting core review label Dec 17, 2023

bedevere-app bot mentioned this pull request Dec 17, 2023

Fix all Sphinx reference warnings in the documentation #101100

Open

hugovk added skip news docs Documentation in the Doc dir needs backport to 3.11 only security fixes needs backport to 3.12 only security fixes labels Dec 17, 2023

willingc approved these changes Dec 17, 2023

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Dec 17, 2023

hugovk merged commit f428c4d into python:main Dec 18, 2023

hugovk deleted the docs-fix-sphinx-warnings-tarfile branch December 18, 2023 06:57

bedevere-app bot removed the awaiting merge label Dec 18, 2023

miss-islington-app bot assigned hugovk Dec 18, 2023

bedevere-app bot removed the needs backport to 3.12 only security fixes label Dec 18, 2023

bedevere-app bot removed the needs backport to 3.11 only security fixes label Dec 18, 2023

hugovk added a commit that referenced this pull request Dec 18, 2023

[3.12] gh-101100: Fix Sphinx warnings in library/tarfile.rst (GH-113237…

e23657f

…) (#113244)

hugovk added a commit that referenced this pull request Dec 18, 2023

[3.11] gh-101100: Fix Sphinx warnings in library/tarfile.rst (GH-113237…

bd8aa9d

…) (#113245)

ryan-duve pushed a commit to ryan-duve/cpython that referenced this pull request Dec 26, 2023

pythongh-101100: Fix Sphinx warnings in library/tarfile.rst (python#1…

22db91c

…13237) Fix Sphinx warnings in library/tarfile.rst

aisk pushed a commit to aisk/cpython that referenced this pull request Feb 11, 2024

pythongh-101100: Fix Sphinx warnings in library/tarfile.rst (python#1…

d847969

…13237) Fix Sphinx warnings in library/tarfile.rst

Glyphack pushed a commit to Glyphack/cpython that referenced this pull request Sep 2, 2024

pythongh-101100: Fix Sphinx warnings in library/tarfile.rst (python#1…

5806697

…13237) Fix Sphinx warnings in library/tarfile.rst

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

hugovk commented Dec 17, 2023 •

edited

Loading

willingc left a comment

willingc Dec 17, 2023

hugovk Dec 17, 2023 •

edited

Loading

miss-islington-app bot commented Dec 18, 2023

miss-islington-app bot commented Dec 18, 2023

miss-islington-app bot commented Dec 18, 2023

bedevere-app bot commented Dec 18, 2023

bedevere-app bot commented Dec 18, 2023

	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

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

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

Conversation

hugovk commented Dec 17, 2023 • edited Loading

willingc left a comment

Choose a reason for hiding this comment

willingc Dec 17, 2023

Choose a reason for hiding this comment

hugovk Dec 17, 2023 • edited Loading

Choose a reason for hiding this comment

miss-islington-app bot commented Dec 18, 2023

miss-islington-app bot commented Dec 18, 2023

miss-islington-app bot commented Dec 18, 2023

bedevere-app bot commented Dec 18, 2023

bedevere-app bot commented Dec 18, 2023

hugovk commented Dec 17, 2023 •

edited

Loading

hugovk Dec 17, 2023 •

edited

Loading