◐ Shell
reader mode source ↗
Skip to content

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

Merged
hugovk merged 2 commits into
python:mainfrom
sobolevn:issue-101100-tutorial-appendix
Sep 1, 2023
Merged

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

Conversation

@sobolevn

@sobolevn sobolevn commented Sep 1, 2023 •
edited
Loading

Copy link
Copy Markdown
Member

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.

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

@sobolevn sobolevn requested a review from hugovk September 1, 2023 08:44
@bedevere-bot bedevere-bot mentioned this pull request Sep 1, 2023
Open
@hugovk hugovk enabled auto-merge (squash) September 1, 2023 10:47
@hugovk hugovk merged commit 3047f09 into python:main Sep 1, 2023
@miss-islington

miss-islington commented Sep 1, 2023

Copy link
Copy Markdown
Contributor

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

@bedevere-bot

This comment was marked as off-topic.

Sign in to view
@miss-islington

miss-islington commented Sep 1, 2023

Copy link
Copy Markdown
Contributor

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

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

bedevere-bot commented Sep 1, 2023

Copy link
Copy Markdown

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

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Sep 1, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 1, 2023
@sobolevn @hugovk @miss-islington
pythongh-101100: Fix sphinx warnings in tutorial/appendix.rst (pyth… …
63f3f70 
…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>
hugovk added a commit that referenced this pull request Sep 1, 2023
@miss-islington @sobolevn @hugovk
[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>
hugovk pushed a commit to hugovk/cpython that referenced this pull request Sep 1, 2023
@sobolevn @hugovk
[3.12] pythongh-101100: Fix sphinx warnings in tutorial/appendix.rst ( …
1e5a8a4 
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>
hugovk pushed a commit to hugovk/cpython that referenced this pull request Sep 1, 2023
@sobolevn @hugovk
[3.12] pythongh-101100: Fix sphinx warnings in tutorial/appendix.rst ( …
9972b52 
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>
@bedevere-bot

bedevere-bot commented Sep 1, 2023

Copy link
Copy Markdown

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

@bedevere-bot 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
@hugovk @sobolevn
[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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hugovk hugovk Awaiting requested review from hugovk hugovk is a code owner

Assignees

@hugovk hugovk

Labels

awaiting core review docs Documentation in the Doc dir skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@sobolevn @miss-islington @bedevere-bot @hugovk