Add more links and cross-references#28
Merged
mgorny merged 2 commits intopep-wheel-variants-stagefrom Dec 10, 2025
Merged
Conversation
Add links to projects we're talking about, when we're referencing them for the first time or haven't mentioned them in a while. Add more cross-references to make finding relevant bits easier, especially if we're talking about something that's specified later on. Cross-link to specifications more. Signed-off-by: Michał Górny <mgorny@quansight.com>
rgommers
reviewed
Dec 10, 2025
| in modern hardware. | ||
|
|
||
| For example, packages such as `PyTorch <https://pytorch.org/>`__ need to | ||
| For example, packages such as `PyTorch <https://pytorch.org/>`_ need to |
There was a problem hiding this comment.
I didn't check the rendering locally, but a little surprising that this is better - double underscore is standard in reST I think. What changes here?
Author
There was a problem hiding this comment.
Single underscore means named links, i.e. links you can reference afterwards without repeating the URL. Double underscore means anonymous links, i.e. without that property — I'm using them when the link name is not actually a meaningful keyword.
rgommers
reviewed
Dec 10, 2025
rgommers
approved these changes
Dec 10, 2025
rgommers
left a comment
rgommers
left a comment
There was a problem hiding this comment.
LGTM modulo my couple of very minor comments
Signed-off-by: Michał Górny <mgorny@quansight.com>
DEKHTIARJonathan
added a commit
that referenced
this pull request
Dec 10, 2025
* PEP 815: Raw conversion from the "Wheel Variants" Markdown Done via: ``` m2r2 --no-underscore-emphasis pepxxx_wheel_variant_support.md ``` Signed-off-by: Michał Górny <mgorny@quansight.com> * Add proper PEP headers Signed-off-by: Michał Górny <mgorny@quansight.com> * PEP 815: fix hyperlink conflicts Signed-off-by: Michał Górny <mgorny@quansight.com> * Remove incorrect lexers Signed-off-by: Michał Górny <mgorny@quansight.com> * Copy assets over Signed-off-by: Michał Górny <mgorny@quansight.com> * Fix pre-commit issues Signed-off-by: Michał Górny <mgorny@quansight.com> * Sync PEP 440 ref removal Signed-off-by: Michał Górny <mgorny@quansight.com> * Update Konstantin's name Signed-off-by: Michał Górny <mgorny@quansight.com> * Fix pre-commit issues Signed-off-by: Michał Górny <mgorny@quansight.com> * Update heading style per PEP 12 Signed-off-by: Michał Górny <mgorny@quansight.com> * Fix spacing around headings Signed-off-by: Michał Górny <mgorny@quansight.com> * Restart with pandoc The pandoc's conversion is much better. Signed-off-by: Michał Górny <mgorny@quansight.com> * Fix headings again Signed-off-by: Michał Górny <mgorny@quansight.com> * Fix appendix references Signed-off-by: Michał Górny <mgorny@quansight.com> * Fix code blocks Signed-off-by: Michał Górny <mgorny@quansight.com> * Reindent code blocks & fix syntax hl Signed-off-by: Michał Górny <mgorny@quansight.com> * Diversify list enumerators Signed-off-by: Michał Górny <mgorny@quansight.com> * Use definition list for glossary Signed-off-by: Michał Górny <mgorny@quansight.com> * Use enumerated lists when we say "three" Signed-off-by: Michał Górny <mgorny@quansight.com> * Reflow Signed-off-by: Michał Górny <mgorny@quansight.com> * Provide alt text for images Signed-off-by: Michał Górny <mgorny@quansight.com> * Make use of cross-references Signed-off-by: Michał Górny <mgorny@quansight.com> * WHLNXT render * Apply suggestions from code review Co-authored-by: Charlie Marsh <crmarsh416@gmail.com> * Apply suggestion from @charliermarsh Co-authored-by: Charlie Marsh <crmarsh416@gmail.com> * Include problems with depending on "package name" variants #6 (comment) Signed-off-by: Michał Górny <mgorny@quansight.com> * Extend risks for fetching via sdist #6 (comment) Signed-off-by: Michał Górny <mgorny@quansight.com> * Apply suggestion from @jithunnair-amd Co-authored-by: Jithun Nair <37884920+jithunnair-amd@users.noreply.github.com> * Reduce size of PEP 815 images using oxipng This commit reduces the size of the images associated with PEP 815 by ~40% each. The commandline used to reduce the size was `oxipng -o 6 --strip safe --alpha $file`. * Apply suggestions from code review Co-authored-by: Emma Smith <emsmith@nvidia.com> * Apply suggestion from @emmatyping-nv Co-authored-by: Emma Smith <emsmith@nvidia.com> * Suggestions from @rgommers (#8) * Update the bit about SciPy Thanks to @rgommers in #6 (comment). Signed-off-by: Michał Górny <mgorny@quansight.com> * Sync quotes from wheelnext/wheelnext#110 Signed-off-by: Michał Górny <mgorny@quansight.com> * Provide examples early in the motivation section Per #6 (comment). Signed-off-by: Michał Górny <mgorny@quansight.com> * Improve the FlashAttention section Don't use tool-specific option, mention the caching problem and better describe why it's no build isolation. * Apply suggestion from @mgorny * Replace non-breaking spaces with regular ones The regular spaces are ASCII characters, while the non-breaking spaces are special Unicode characters. There's no need in our text to use non-breaking spaces, such as there would be with SI units. * Fix a few conversion errors Signed-off-by: Michał Górny <mgorny@quansight.com> * Try to clarify variant ordering in overview #6 (comment) Signed-off-by: Michał Górny <mgorny@quansight.com> * Clarify behavior for no non-variant wheels #6 (comment) Signed-off-by: Michał Górny <mgorny@quansight.com> * Apply suggestion from @emmatyping-nv Co-authored-by: Emma Smith <emsmith@nvidia.com> * Explain install-time/AoT plugins in detail in rationale Signed-off-by: Michał Górny <mgorny@quansight.com> * Apply suggestion from @emmatyping-nv Co-authored-by: Emma Smith <emsmith@nvidia.com> * Bump pygments requirement Not sure if we should do that as part of the PEP submission, but we are using lexers available since 2.19.0, as @konstin noticed. Signed-off-by: Michał Górny <mgorny@quansight.com> * Move "Security implications" before the "Specification" Signed-off-by: Michał Górny <mgorny@quansight.com> * Expand on the risks and attack scenarios Signed-off-by: Michał Górny <mgorny@quansight.com> * Avoid pip-specific options Signed-off-by: Michał Górny <mgorny@quansight.com> * Try to emphasize vendoring plugins more Signed-off-by: Michał Górny <mgorny@quansight.com> * Apply suggestion from @konstin Co-authored-by: konsti <konstin@mailbox.org> * Fix trailing whitespace Signed-off-by: Michał Górny <mgorny@quansight.com> * Put more focus on torch (#12) * Put more focus on torch * Update peps/pep-0815.rst Co-authored-by: Michał Górny <mgorny@gentoo.org> * Update peps/pep-0815.rst Co-authored-by: Michał Górny <mgorny@gentoo.org> * Update peps/pep-0815.rst Co-authored-by: Michał Górny <mgorny@gentoo.org> --------- Co-authored-by: Michał Górny <mgorny@gentoo.org> * Drop "and more" from use examples Signed-off-by: Michał Górny <mgorny@quansight.com> * Remove unnecessary paragraph below GROMACS benchmark Signed-off-by: Michał Górny <mgorny@quansight.com> * Remove graphics/gaming case Signed-off-by: Michał Górny <mgorny@quansight.com> * Include more wheel tag examples Signed-off-by: Michał Górny <mgorny@quansight.com> * Remove redundant "user stories" Signed-off-by: Michał Górny <mgorny@quansight.com> * Correct CPU instruction paragraph Signed-off-by: Michał Górny <mgorny@quansight.com> * Improve the GPU paragraph Signed-off-by: Michał Górny <mgorny@quansight.com> * Remove intro to "current workarounds..." Signed-off-by: Michał Górny <mgorny@quansight.com> * Replace documentation burden with error-proneness Signed-off-by: Michał Górny <mgorny@quansight.com> * Add a note what SMs are Signed-off-by: Michał Górny <mgorny@quansight.com> * Replace the schema URL TODO Signed-off-by: Michał Górny <mgorny@quansight.com> * Apply suggestions by @konstin Signed-off-by: Michał Górny <mgorny@quansight.com> * Add a quote from PyTorch maintainers Fixes: wheelnext/wheelnext#111 Signed-off-by: Michał Górny <mgorny@quansight.com> * Clarify how variants.json is presented on an index * Update peps/pep-0815.rst Co-authored-by: Emma Smith <emsmith@nvidia.com> * Line wrapping * Expand wheel tag descriptions to match detail from abstract Signed-off-by: Michał Górny <mgorny@quansight.com> * Shorten the abstract a bit Signed-off-by: Michał Górny <mgorny@quansight.com> * Replace the x86-64 level paragraph Signed-off-by: Michał Górny <mgorny@quansight.com> * Add a link to the uv reference implementation branch #6 (comment) * Update Charlie's e-mail address Signed-off-by: Michał Górny <mgorny@quansight.com> * Make the beginning of motivation more illustrative Attempting to address #6 (comment) Signed-off-by: Michał Górny <mgorny@quansight.com> * Rewrite the introduction to spec Remove the weird "packaging ecosystem version" and make it clearer what we're talking about. Signed-off-by: Michał Górny <mgorny@quansight.com> * Clarify kinds of tools in the security part of overview #6 (comment) Signed-off-by: Michał Górny <mgorny@quansight.com> * Copy GROMACS chart desc from the paper Signed-off-by: Michał Górny <mgorny@quansight.com> * Some copy-edits to the text for clarity & project names * Acknowledgments Section * Skip build if branch is `norender*` * Linter Fixes * Authors += "Andy R Terrel" * JSON Schema Appendix * Updates on full reread (#25) * Do a grammar run up to "Motivation" section Signed-off-by: Michał Górny <mgorny@quansight.com> * Extend "variant properties system" slightly Add an introduction on what they are, and mention that they are stored in the metadata. This makes the text easier to process when you are reading top-to-bottom, given that variant properties haven't been introduced yet. Signed-off-by: Michał Górny <mgorny@quansight.com> * Rewrite the null variant rationale Rewrite the rationale null variant for better readability and consistency. Remove redundant half-paragraph. Rewrite the sentences that sound like specification (specification already covers these bits). Signed-off-by: Michał Górny <mgorny@quansight.com> * Clarify the precedence between null variant and non-variant wheels Signed-off-by: Michał Górny <mgorny@quansight.com> * Updates up to "security implications" Signed-off-by: Michał Górny <mgorny@quansight.com> * First part of specification update Signed-off-by: Michał Górny <mgorny@quansight.com> * Final touches to the specification Signed-off-by: Michał Górny <mgorny@quansight.com> * Final sections, finally! Signed-off-by: Michał Górny <mgorny@quansight.com> * Apply suggestions from code review Co-authored-by: konsti <konstin@mailbox.org> * Apply more suggestions from Konsti Signed-off-by: Michał Górny <mgorny@quansight.com> * Restore "a choice" Signed-off-by: Michał Górny <mgorny@quansight.com> * Apply suggestion from @rgommers Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com> * "could leads" → "leads" Signed-off-by: Michał Górny <mgorny@quansight.com> --------- Signed-off-by: Michał Górny <mgorny@quansight.com> Co-authored-by: konsti <konstin@mailbox.org> Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com> * Try a more smooth title (#27) Signed-off-by: Michał Górny <mgorny@quansight.com> * Add more links and cross-references (#28) * Add more links and cross-references Add links to projects we're talking about, when we're referencing them for the first time or haven't mentioned them in a while. Add more cross-references to make finding relevant bits easier, especially if we're talking about something that's specified later on. Cross-link to specifications more. Signed-off-by: Michał Górny <mgorny@quansight.com> * Undo OpenTeams link Signed-off-by: Michał Górny <mgorny@quansight.com> --------- Signed-off-by: Michał Górny <mgorny@quansight.com> --------- Signed-off-by: Michał Górny <mgorny@quansight.com> Co-authored-by: Michał Górny <mgorny@quansight.com> Co-authored-by: Michał Górny <mgorny@gentoo.org> Co-authored-by: Charlie Marsh <crmarsh416@gmail.com> Co-authored-by: Jithun Nair <37884920+jithunnair-amd@users.noreply.github.com> Co-authored-by: Emma Harper Smith <emsmith@nvidia.com> Co-authored-by: konstin <konstin@mailbox.org> Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Add links to projects we're talking about, when we're referencing them for the first time or haven't mentioned them in a while. Add more cross-references to make finding relevant bits easier, especially if we're talking about something that's specified later on. Cross-link to specifications more.