gh-101100: Fix sphinx warnings in `tutorial/appendix.rst` by sobolevn · Pull Request #108750 · python/cpython · GitHub

Warnings before:

/Users/sobolev/Desktop/cpython/Doc/tutorial/appendix.rst:104: WARNING: py:mod reference target not found: sitecustomize
/Users/sobolev/Desktop/cpython/Doc/tutorial/appendix.rst:104: WARNING: py:mod reference target not found: usercustomize
/Users/sobolev/Desktop/cpython/Doc/tutorial/appendix.rst:116: WARNING: py:mod reference target not found: sitecustomize
/Users/sobolev/Desktop/cpython/Doc/tutorial/appendix.rst:116: WARNING: py:mod reference target not found: usercustomize

The problem here is that these module are not documented as .. module::, they are documented as .. index instead https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index

cpython/Doc/library/site.rst

Lines 112 to 126 in 044b8b3

    
           .. index:: pair: module; sitecustomize 
        
           After these path manipulations, an attempt is made to import a module named 
        
           :mod:`sitecustomize`, which can perform arbitrary site-specific customizations. 
        
           It is typically created by a system administrator in the site-packages 
        
           directory.  If this import fails with an :exc:`ImportError` or its subclass 
        
           exception, and the exception's :attr:`name` attribute equals to ``'sitecustomize'``, 
        
           it is silently ignored.  If Python is started without output streams available, as 
        
           with :file:`pythonw.exe` on Windows (which is used by default to start IDLE), 
        
           attempted output from :mod:`sitecustomize` is ignored.  Any other exception 
        
           causes a silent and perhaps mysterious failure of the process. 
        
           .. index:: pair: module; usercustomize 
        
           After this, an attempt is made to import a module named :mod:`usercustomize`,

So, I went with :index: inline role. This way once some location is added to their definitions (a header, probably) they will automatically link there.

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

📚 Documentation preview 📚: https://cpython-previews--108750.org.readthedocs.build/

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

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

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

…onGH-108750) (cherry picked from commit 3047f09) Co-authored-by: Nikita Sobolev <mail@sobolevn.me> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

…108750) (#108757) Co-authored-by: Nikita Sobolev <mail@sobolevn.me> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

pythonGH-108750) Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>. (cherry picked from commit 3047f09) Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

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

…108750) (#108759) (cherry picked from commit 3047f09) Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

pythongh-101100 : Fix sphinx warnings in tutorial/appendix.rst

90f5ffb

sobolevn requested a review from hugovk September 1, 2023 08:44

bedevere-bot mentioned this pull request Sep 1, 2023

Fix all Sphinx reference warnings in the documentation #101100

Closed

bedevere-bot added the awaiting review label Sep 1, 2023

sobolevn added docs Documentation in the Doc dir skip news labels Sep 1, 2023

Merge branch 'main' into issue-101100-tutorial-appendix

24be2da

hugovk approved these changes Sep 1, 2023

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting review labels Sep 1, 2023

hugovk enabled auto-merge (squash) September 1, 2023 10:47

hugovk added needs backport to 3.11 only security fixes needs backport to 3.12 only security fixes labels Sep 1, 2023

hugovk merged commit 3047f09 into python:main Sep 1, 2023

bedevere-bot added awaiting core review and removed awaiting merge labels Sep 1, 2023

This comment was marked as off-topic.

Sign in to view

bedevere-bot requested a review from hugovk September 1, 2023 10:57

miss-islington assigned hugovk Sep 1, 2023

bedevere-bot removed the needs backport to 3.11 only security fixes label Sep 1, 2023

hugovk added a commit that referenced this pull request Sep 1, 2023

[3.11] gh-101100 : Fix sphinx warnings in tutorial/appendix.rst (GH-…

d3476dc

…108750) (#108757) Co-authored-by: Nikita Sobolev <mail@sobolevn.me> Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

bedevere-bot removed the needs backport to 3.12 only security fixes label Sep 1, 2023

Yhg1s pushed a commit that referenced this pull request Sep 2, 2023

[3.12] gh-101100 : Fix sphinx warnings in tutorial/appendix.rst (GH-…

f58617a

…108750) (#108759) (cherry picked from commit 3047f09) Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

gh-101100: Fix sphinx warnings in `tutorial/appendix.rst` by sobolevn · Pull Request #108750 · python/cpython · GitHub

Repository navigation

gh-101100: Fix sphinx warnings in tutorial/appendix.rst - #108750

gh-101100: Fix sphinx warnings in tutorial/appendix.rst#108750
hugovk merged 2 commits into
python:mainfrom
sobolevn:issue-101100-tutorial-appendix

sobolevn commented Sep 1, 2023 •
edited
Loading

Uh oh!

Uh oh!

miss-islington commented Sep 1, 2023

Uh oh!

This comment was marked as off-topic.

miss-islington commented Sep 1, 2023

Uh oh!

bedevere-bot commented Sep 1, 2023

Uh oh!

bedevere-bot commented Sep 1, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	.. index:: pair: module; sitecustomize

	After these path manipulations, an attempt is made to import a module named
	:mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
	It is typically created by a system administrator in the site-packages
	directory. If this import fails with an :exc:`ImportError` or its subclass
	exception, and the exception's :attr:`name` attribute equals to ``'sitecustomize'``,
	it is silently ignored. If Python is started without output streams available, as
	with :file:`pythonw.exe` on Windows (which is used by default to start IDLE),
	attempted output from :mod:`sitecustomize` is ignored. Any other exception
	causes a silent and perhaps mysterious failure of the process.

	.. index:: pair: module; usercustomize

	After this, an attempt is made to import a module named :mod:`usercustomize`,

gh-101100: Fix sphinx warnings in `tutorial/appendix.rst` by sobolevn · Pull Request #108750 · python/cpython · GitHub

Repository navigation

gh-101100: Fix sphinx warnings in tutorial/appendix.rst - #108750

gh-101100: Fix sphinx warnings in tutorial/appendix.rst#108750hugovk merged 2 commits intopython:mainpython/cpython:mainfrom sobolevn:issue-101100-tutorial-appendixsobolevn/cpython:issue-101100-tutorial-appendixCopy head branch name to clipboard

Conversation

sobolevn commented Sep 1, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

miss-islington commented Sep 1, 2023

Uh oh!

This comment was marked as off-topic.

miss-islington commented Sep 1, 2023

Uh oh!

bedevere-bot commented Sep 1, 2023

Uh oh!

bedevere-bot commented Sep 1, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gh-101100: Fix sphinx warnings in tutorial/appendix.rst#108750
hugovk merged 2 commits into
python:mainfrom
sobolevn:issue-101100-tutorial-appendix

sobolevn commented Sep 1, 2023 •
edited
Loading