GV

GeezerVison

The World Wide Web, restored to 800 pixels of glory.

Home|About|Gaming cabinet|Archives|How it works|Starter sites

On this site

  • Sign in
  • ActionsCI/CD and automation
  • CodespacesCloud development environments
  • All Features
  • Documentation
  • Training
  • Certifications
  • Build with Copilot
  • Customize Copilot
  • Integrations
  • Trending repos
  • GitHub Sponsors
  • Developer articles
  • Enterprises

This view

  • Original page
  • New address

GeezerVison is showing github.com — Use `:cpy-file:` throughout the Devguide by ezio-melotti · Pull Request #984 · python/devguide

Conversation

@ezio-melotti

@ezio-melotti ezio-melotti commented Nov 14, 2022

Copy link
Copy Markdown
Member

This PR replaces the use of :file: with :cpy-file: (introduced in #961) in most places. Since the generated links are now checked by make linkcheck, I also went through and corrected some of those.

There are a few broken links that I haven't touched yet:

(developer-workflow/grammar: line 40) broken https://github.com/python/cpython/blob/main/Include/Python-ast.h
(developer-workflow/grammar: line 33) broken https://github.com/python/cpython/blob/main/Include/token.h
(internals/compiler: line 516) broken https://github.com/python/cpython/blob/main/Include/code.h
(internals/compiler: line 488) broken https://github.com/python/cpython/blob/main/Python/peephole.c

  • Include/Python-ast.h was removed by @vstinner
    • bpo-43244: Remove ast.h, asdl.h, Python-ast.h headers cpython#24933
  • Include/token.h was removed by @vstinner
    • gh-92651: Remove the Include/token.h header file cpython#92652
  • Include/code.h was removed by @vstinner
    • bpo-35134: Remove the Include/code.h header file cpython#32385
  • Python/peephole.c was removed by @markshannon
    • bpo-41323: Perform 'peephole' optimizations directly on the CFG. cpython#21517

The respective sections in developer-workflow/grammar.rst and internals/compiler.rst might need to be revisited.
@vstinner and @markshannon: can you advise on whether these are quick fixes that we can include in this PR or if they should be handled separately?

I also found another issue with this section: https://devguide.python.org/internals/compiler/#important-files
In addition to the fact that the listed files don't use any markup, the markup used for most of the files seem incorrect (it's a blockquote due to the indentation). A nested list with full paths for all the files and :cpy-file: should be a better alternative.

The :cpy-file: role could also be improved to support ~, so that in that list (and in a few other places) we can hide the full path and just display the file name.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
ezio-melotti added 2 commits November 13, 2022 21:56
@ezio-melotti
Use :cpy-file: throughout the Devguide.
15c1517
@ezio-melotti
Fix broken file paths.
a65508a
@ezio-melotti ezio-melotti added the type-feature Additions; New content or section needed label Nov 14, 2022
@ezio-melotti
ezio-melotti requested a review from CAM-Gerlach November 14, 2022 05:19
@ezio-melotti ezio-melotti self-assigned this Nov 14, 2022
ezio-melotti
ezio-melotti commented Nov 14, 2022
View reviewed changes
Comment thread core-developers/experts.rst
Developers can choose to follow labels, so if a label that they are
following is added to an issue or pull request, they will be notified
automatically. The :file:`CODEOWNERS` file is also used to indicate
automatically. The :cpy-file:`.github/CODEOWNERS` file is also used to indicate

@ezio-melotti ezio-melotti Nov 14, 2022

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

If we add ~ support to :cpy-file: we could hide the dir.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread developer-workflow/c-api.rst
Functions named ``test_*`` are used as tests directly.
Tests that need Python code (or are just easier to partially write in Python)
live in ``Lib/test``, mainly in :file:`Lib/test/test_capi.py`.
live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi`.

@ezio-melotti ezio-melotti Nov 14, 2022

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

test_capi is now a dir.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread internals/compiler.rst
very beginning of the compiler or the end, you need to care about how the arena
works. All code relating to the arena is in either
:file:`Include/Internal/pycore_pyarena.h` or :file:`Python/pyarena.c`.
:cpy-file:`Include/internal/pycore_pyarena.h` or :cpy-file:`Python/pyarena.c`.

@ezio-melotti ezio-melotti Nov 14, 2022

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

internal is lowercase. There were a few similar errors in this file.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread internals/compiler.rst
@@ -532,12 +535,12 @@ Important Files

asdl_c.py

@ezio-melotti ezio-melotti Nov 14, 2022

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

All the files in this section should be linkified. I left a comment about it in the PR.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@ezio-melotti ezio-melotti mentioned this pull request Nov 14, 2022
Add a Sphinx role to link to GitHub files #961
Merged
hugovk
hugovk approved these changes Nov 29, 2022
View reviewed changes

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Gave a few a spot check, looks good.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
Comment thread developer-workflow/c-api.rst
Functions named ``test_*`` are used as tests directly.
Tests that need Python code (or are just easier to partially write in Python)
live in ``Lib/test``, mainly in :file:`Lib/test/test_capi.py`.
live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi`.

@hugovk hugovk Nov 29, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

We could also link things that aren't already :file:, like Lib/test:

Suggested change
live in ``Lib/test``, mainly in :cpy-file:`Lib/test/test_capi`.
live in :cpy-file:`Lib/test`, mainly in :cpy-file:`Lib/test/test_capi`.

There's a lot more that could be linked on this page too, especially the first few sections.

But let's keep the scope of this PR to replacing the old :file: with the new :cpy-file:.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

ezio-melotti and CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 2 reactions

@ezio-melotti ezio-melotti Nov 29, 2022

Copy link
Copy Markdown
Member Author

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

Agreed on keeping the PR focused. We should also try to create links only when/where they are useful, but there are definitely more places where :cpy-file: can be used.

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

hugovk and CAM-Gerlach reacted with thumbs up emoji
All reactions
  • 👍 2 reactions

@CAM-Gerlach CAM-Gerlach Nov 30, 2022

Copy link
Copy Markdown
Member

There was a problem hiding this comment.

Choose a reason for hiding this comment

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

That SGTM

Sorry, something went wrong.

Uh oh!

There was an error while loading. Please reload this page.

All reactions
@ezio-melotti
Merge remote-tracking branch 'upstream/main' into use-cpy-file
2379ad4
@ezio-melotti ezio-melotti mentioned this pull request Dec 9, 2022
Fix links to missing CPython files #1003
Open
@ezio-melotti
ezio-melotti merged commit 71e46f0 into python:main Dec 9, 2022
@ezio-melotti
ezio-melotti deleted the use-cpy-file branch December 9, 2022 09:51
@ezio-melotti ezio-melotti mentioned this pull request Dec 9, 2022
Reformat "Important Files" section in compiler.rst #1004
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hugovk hugovk hugovk approved these changes
@CAM-Gerlach CAM-Gerlach Awaiting requested review from CAM-Gerlach

Uh oh!

There was an error while loading. Please reload this page.

Assignees

@ezio-melotti ezio-melotti

Labels

type-feature Additions; New content or section needed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Uh oh!

There was an error while loading. Please reload this page.

3 participants

@ezio-melotti @hugovk @CAM-Gerlach
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.