Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

docs: module page titles should not start with a link to themselves#117099

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.

Already on GitHub?Sign in to your account

Merged

Conversation

nedbat
Copy link
Member

@nedbatnedbat commentedMar 20, 2024•
edited
Loading

The:mod: role used in the title of module pages turns into a link, but the link is to the same page. That's distracting and unhelpful. This uses the! prefix to instruct Sphinx to not make a link.

This was done with this thrown-together program:

"""Change every module page in the CPython docsso that the title doesn't link to itself."""frompathlibimportPath# Edge cases:# - modules with a blank line at the top.# - modules that already had the !-prefix to suppress the link.# - had to fix the rule length# - pages that started with a link, but to the main module page.#       unittest.mock-examples.rst# - pages with slightly off names:#       xml.sax.xmlreader is in xml.sax.reader.rst#       xml.etree.ElementTree is in xml.etree.elementtree.rst#       xml.parsers.expat is in pyexpat.rst#       xml.sax.saxutils is in xml.sax.utils.rst# - pages with two links in the title!#       copyreg.rstdeffix_one_file(fpath):text=fpath.read_text().lstrip()ifnottext.startswith(":mod:`"):returniftext.startswith(":mod:`!"):returnlines=text.splitlines(keepends=True)modname=lines[0].split("`")[1]ifmodname!=fpath.stem:print(f"WUT:{modname=},{fpath.stem=}")lines[0]=lines[0].replace(":mod:`",":mod:`!")lines[1]=lines[1][0]* (len(lines[0])-1)+"\n"fpath.write_text("".join(lines))print(f"Updated{fpath}")forfnameinPath(".").glob("**/*.rst"):fix_one_file(fname)

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

@bedevere-appbedevere-appbot added docsDocumentation in the Doc dir skip news labelsMar 20, 2024
@nedbat
Copy link
MemberAuthor

This is only marked Draft because I didn't want to ping 29 other people for review. Can that be stopped?

@AlexWaygood
Copy link
Member

This is only marked Draft because I didn't want to ping 29 other people for review. Can that be stopped?

I don't know of a way of avoiding that, unfortunately... It's not possible for me to deselect any of the codeowners from the list of people who are going to be requested for review.

@nedbatnedbatforce-pushed thenedbat/dont-self-link-module-pages branch fromc711468 to1485c51CompareMarch 20, 2024 20:34
Copy link
Member

@AlexWaygoodAlexWaygood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

LGTM, thanks! I agree that these are distracting for readers, and serve no purpose.

While I agree with@CAM-Gerlach's comments on Discord that a Sphinx extension might be a cleaner way of fixing this, I'm personally happy to merge this unless somebody wants to volunteer to actually do that. I think we should prioritise the experience for readers of the docs, and this PR improves the experience of reading the docs.

hugovk and serhiy-storchaka reacted with thumbs up emoji
@nedbat
Copy link
MemberAuthor

Since I don't want to ping 29 code owners, and am a little bit interested in learning about Sphinx internals, let's wait on this to see how the CAM+Ned tag team manages on tweaking Sphinx.

AlexWaygood and hugovk reacted with thumbs up emoji

@nedbat
Copy link
MemberAuthor

Everyone: I know this might ping many people. My apologies. The changes were auto-created across all of the module pages.

Copy link
Member

@serhiy-storchakaserhiy-storchaka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

LGTM.

How we did not notice this earlier?

@serhiy-storchakaserhiy-storchaka added needs backport to 3.13bugs and security fixes needs backport to 3.12only security fixes labelsMay 8, 2024
@AlexWaygoodAlexWaygood merged commitbcb435e intopython:mainMay 8, 2024
@miss-islington-app
Copy link

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull requestMay 8, 2024
…ythonGH-117099)(cherry picked from commitbcb435e)Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull requestMay 8, 2024
…ythonGH-117099)(cherry picked from commitbcb435e)Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
@bedevere-app
Copy link

GH-118790 is a backport of this pull request to the3.13 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.13bugs and security fixes labelMay 8, 2024
@bedevere-app
Copy link

GH-118791 is a backport of this pull request to the3.12 branch.

@bedevere-appbedevere-appbot removed the needs backport to 3.12only security fixes labelMay 8, 2024
AlexWaygood pushed a commit that referenced this pull requestMay 8, 2024
…elves (GH-117099) (#118791)docs: module page titles should not start with a link to themselves (GH-117099)(cherry picked from commitbcb435e)Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
AlexWaygood pushed a commit that referenced this pull requestMay 8, 2024
…elves (GH-117099) (#118790)docs: module page titles should not start with a link to themselves (GH-117099)(cherry picked from commitbcb435e)Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
@nedbatnedbat deleted the nedbat/dont-self-link-module-pages branchMay 21, 2024 22:13
Sign up for freeto join this conversation on GitHub. Already have an account?Sign in to comment
Reviewers

@serhiy-storchakaserhiy-storchakaserhiy-storchaka approved these changes

@erlend-aaslanderlend-aaslanderlend-aasland approved these changes

@ezio-melottiezio-melottiezio-melotti approved these changes

@JacobCoffeeJacobCoffeeJacobCoffee approved these changes

@AlexWaygoodAlexWaygoodAlexWaygood approved these changes

@hugovkhugovkAwaiting requested review from hugovk

@barneygalebarneygaleAwaiting requested review from barneygalebarneygale is a code owner

@FFY00FFY00Awaiting requested review from FFY00FFY00 is a code owner

@encukouencukouAwaiting requested review from encukouencukou is a code owner

@hauntsaninjahauntsaninjaAwaiting requested review from hauntsaninjahauntsaninja is a code owner

@ethanfurmanethanfurmanAwaiting requested review from ethanfurmanethanfurman is a code owner

@pfmoorepfmooreAwaiting requested review from pfmoorepfmoore is a code owner

@pradyunsgpradyunsgAwaiting requested review from pradyunsgpradyunsg is a code owner

@ericvsmithericvsmithAwaiting requested review from ericvsmithericvsmith is a code owner

@rhettingerrhettingerAwaiting requested review from rhettingerrhettinger is a code owner

@berkerpeksagberkerpeksagAwaiting requested review from berkerpeksagberkerpeksag is a code owner

@gpsheadgpsheadAwaiting requested review from gpsheadgpshead is a code owner

@pablogsalpablogsalAwaiting requested review from pablogsalpablogsal is a code owner

@pgansslepganssleAwaiting requested review from pgansslepganssle is a code owner

@abalkinabalkinAwaiting requested review from abalkinabalkin is a code owner

@ericsnowcurrentlyericsnowcurrentlyAwaiting requested review from ericsnowcurrentlyericsnowcurrently is a code owner

@brettcannonbrettcannonAwaiting requested review from brettcannonbrettcannon is a code owner

@ncoghlanncoghlanAwaiting requested review from ncoghlanncoghlan is a code owner

@warsawwarsawAwaiting requested review from warsawwarsaw is a code owner

@vsajipvsajipAwaiting requested review from vsajipvsajip is a code owner

@tirantiranAwaiting requested review from tirantiran is a code owner

@corona10corona10Awaiting requested review from corona10corona10 is a code owner

@1st11st1Awaiting requested review from 1st11st1 is a code owner

@asvetlovasvetlovAwaiting requested review from asvetlovasvetlov is a code owner

@gvanrossumgvanrossumAwaiting requested review from gvanrossum

@kumaraditya303kumaraditya303Awaiting requested review from kumaraditya303kumaraditya303 is a code owner

@willingcwillingcAwaiting requested review from willingcwillingc is a code owner

Assignees
No one assigned
Labels
docsDocumentation in the Doc dirskip issueskip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

6 participants
@nedbat@AlexWaygood@serhiy-storchaka@erlend-aasland@ezio-melotti@JacobCoffee
[8]ページ先頭
©2009-2025 Movatter.jp