Move the "quick reference" to a dedicated page by sirosen · Pull Request #1838 · python/devguide

sirosen · 2026-06-13T23:45:07Z

A new page at Getting Started > Quick Reference is added to contain the
(moved) content which was in the Quick Reference section of the index
document for the site.

The content is left almost entirely untouched, but the introductory text
is slightly altered to de-emphasize use of the doc for new contributors.

Intentionally, as described in #1837, the page is placed in Getting
Started but after the setup guide.

closes #1837

A new page at `Getting Started > Quick Reference` is added to contain the (moved) content which was in the Quick Reference section of the index document for the site. The content is left almost entirely untouched, but the introductory text is slightly altered to de-emphasize use of the doc for new contributors. Intentionally, as described in python#1837, the page is placed in Getting Started but after the setup guide.

read-the-docs-community · 2026-06-13T23:46:10Z

Documentation build overview

📚 CPython devguide | 🛠️ Build #33233265 | 📁 Comparing 86f942c against latest (24065f9)

🔍 Preview build

7 files changed · + 1 added · ± 6 modified

+ Added

getting-started/quick-reference/index.html

± Modified

StanFromIreland · 2026-06-14T08:20:12Z

+Here are the basic steps needed to get set up and open a pull request.
+
+This is meant as a checklist and cheat-sheet, not a comprehensive guide.
+For complete instructions please see the :ref:`setup guide <setup>`.


I don't think this makes sense now, we redirect people back to the page they've just read?

This doesn't go back to the home page. It goes to a detailed page about git etc.

I was not referring to the home page. As @sirosen noted in the PR description:

the page is placed in Getting Started but after the setup guide.

We're sending them back to the page just before.

I see, sorry. So we should move this up in the contents.

I think we can rename it to "Overview," and make it an index for the overall quite long "Getting started" section. Additionally, we could merge it with the other Quick Guide, and add a link to the Where to get help at the end. Some of the steps could also use additional links to the more detailed sections.

I would love to see this page be minimalist visually and cheatsheet-like. I think @StanFromIreland is on the right track though "Overview" feels too broad.

Additionally, we could merge it with the other Quick Guide, and add a link to the Where to get help at the end.

Oh no! I didn't realize that there was another, other-other quick reference. 😂

My initial reaction is that I think these should be combined, still in the form of a new page.

I need to do some careful cross-comparison of the content and see if such a change is feasible in practice, without this PR growing too large in scope.

StanFromIreland · 2026-06-14T08:20:40Z

+
+         PCbuild\build.bat -e -d
+
+   See also :ref:`more detailed instructions <compiling>`,


All of the above steps should have been completed by the time they reach this page, so we don't quite need them.

I think all the "see also" items could go later in this document. Perhaps in a "Dive deeper" section.

StanFromIreland · 2026-06-14T08:22:07Z

+
+         .\python.bat -m test -j3
+
+5. Create a new branch where your work for the issue will go, for example::


This section is duplicated by our other "Quick guide".

Steps 5-7 could be their own section or their own page. Keep 1-4 as build from source and run tests.

hugovk · 2026-06-14T08:53:16Z

+.. _quick-reference:
+
+===============
+Quick Reference


Use sentence case for headers:

https://devguide.python.org/documentation/style-guide/#capitalization

Suggested change

Quick Reference

Quick reference

May make sense to be more specific on the title of this doc. Quick reference feels too broad. Something that evokes the original purpose checklist/cheatsheet would make more sense.

We could put it at or near the end of Getting Started, under the name "Workflow cheatsheet".

It would read logically that way, and that name is harmonious with the element of this doc that I'm trying to preserve.

willingc

@sirosen Thanks for following up on the issue that you filed. I think you have some good points. The devguide has evolved quite a bit over the past decade and simplifying the index page makes good sense.

willingc · 2026-06-15T15:46:22Z

   :maxdepth: 5

   setup-building
+   quick-reference


I wonder if it would be better to move this before setup-building. I think we might want to rethink the name "Quick reference". The original text was created to be a checklist/cheatsheet for getting started quickly especially at sprints.

I don't object to making a separate doc for the content. I would leave a clear link/callout in the index page at the same place in the text so that folks who have the page bookmarked for this content know where it moved.

willingc · 2026-06-15T15:48:37Z

+.. _quick-reference:
+
+===============
+Quick Reference


May make sense to be more specific on the title of this doc. Quick reference feels too broad. Something that evokes the original purpose checklist/cheatsheet would make more sense.

willingc · 2026-06-15T15:51:33Z

+Here are the basic steps needed to get set up and open a pull request.
+
+This is meant as a checklist and cheat-sheet, not a comprehensive guide.
+For complete instructions please see the :ref:`setup guide <setup>`.


I would love to see this page be minimalist visually and cheatsheet-like. I think @StanFromIreland is on the right track though "Overview" feels too broad.

willingc · 2026-06-15T15:53:02Z

+
+         PCbuild\build.bat -e -d
+
+   See also :ref:`more detailed instructions <compiling>`,


I think all the "see also" items could go later in this document. Perhaps in a "Dive deeper" section.

willingc · 2026-06-15T15:54:43Z

+
+         .\python.bat -m test -j3
+
+5. Create a new branch where your work for the issue will go, for example::


Steps 5-7 could be their own section or their own page. Keep 1-4 as build from source and run tests.

willingc · 2026-06-15T15:57:07Z

-Quick reference
---------------
-
-Here are the basic steps needed to get set up and open a pull request.


When moving these items to a new page, let's keep the Quick reference title and have an admonition of where the content has moved and why (for approx. 6 months).

We can add a little deferred Javascript redirect for the anchor, e.g.:

function redirectAnchor() { const anchor = window.location.hash.slice(1); if (!anchor || document.getElementById(anchor)) { return; } if (anchor !== "anchor") { return; } window.location.replace(new URL("redirect", window.location.href).href); } redirectAnchor();

I like the idea, but have two reasons I don't want to pursue it at the moment.

Reusability. We probably don't want to do a bespoke bit of JS each time we do a redirect.

I'd like us to pack this idea up to be reusable. I think the redirector you recently proposed for CPython docs was similar -- but I did see that not everyone agreed on that.

Scope creep. This will already end up being a larger PR than I intended.

When I circle back on this, I'll be moving more pieces around and actually changing some content to address feedback. I worry that adding in new code for the site may make this harder to merge, so I'd like to stick strictly to content edits.

(I can definitely take feedback if there's broad agreement that everyone really wants us to add redirectAnchor() right here! But I'm hesitant to embrace the idea without more signal.)

Co-authored-by: Hugo van Kemenade <[email protected]>

The idea of making this section not be first is somewhat at odds with the fact that it needs to link to the first page under Getting Started. It would work to move it to the end, or to the beginning. The beginning seems to be the "least surprise" choice for doc readers and contributors.

Rather than trying to flatten the quick reference into a list (which is too compact!), reflow the doc with each list entry as a section or subsection. The steps are kept very similar to their prior content, but each now ends with a link to more detailed documentation, presented in a slightly more formulaic manner. Links out to GitHub are called out especially to ensure it's clear that they are not parts of the devguide.

Instead of a duplicate guide, we can now link to the canonical quick reference doc.

In the index, ensure that anyone going to the old quick-reference documentation will find a short explanatory note and a link to the new, rehomed quick-reference.

sirosen · 2026-06-21T03:49:20Z

I've just pushed a few changes that attempt to address all of the outstanding review comments.

It seemed to me that I had to choose: (A) double down on this as a "quick start" or "quick reference" and move it to the start of Getting Started (B) adjust phrasing to make this a "cheat sheet" and move it to the end.
I looked at both, thinking I wanted (B), but (A) was much easier to achieve. I kept the name the same, "quick reference", although I somewhat agree with Carol's thought that the name is a bit vague and imperfect -- I just didn't come up with a better one.
I also broke it down into sections, rather than keeping it as a list. It's still very short in content, but it looks bulkier with the section headings. I think that with sections the page makes more sense, as it crosses several topic areas.
Each section links deeply to the matching place in Getting Started (or testing docs, for the testing item).
I eliminated the PR "quick guide" and made sure that the content from there about opening PRs is carried over. A very small amount of content from the start of that section is lost (I noted this in Discord chat; potentially I could file an issue to restore it?).

StanFromIreland · 2026-06-21T09:09:22Z

+   git clone https://github.com/<your_username>/cpython
+   cd cpython
+
+We recommend also setting up ``pre-commit``::


@encukou, are you happy to do this now that we've hash-pinned all the third party hooks?

StanFromIreland · 2026-06-21T09:09:48Z

+
+   .. code-block:: shell
+
+      ./configure --config-cache --with-pydebug && make -j8


Why are we limiting to 8?

Some number is better than none, easy to adjust once you know a number goes there, and arbitrary selection based on market hardware: #1545

If $(nproc) can fail then why not leave it up to make and pass -j (I'm not sure if that works over on macOS, I presume it would be the same as on Linux), it should use all available then.

It depends on the make command. With GNU make:

-j [jobs], --jobs[=jobs] Specifies the number of jobs (commands) to run simultaneously. If there is more than one -j option, the last one is effective. If the -j option is given without an argument, make will not limit the number of jobs that can run simultaneously.

"Don't limit" isn't the same as "use all available".

StanFromIreland · 2026-06-21T09:12:15Z

+   `repository <https://github.com/python/blurb>`__.
+
+For more information on writing news entries,
+see :ref:`"Updating NEWS and What's New in Python" <news-entry>`.


This should be higher, we don't want unnecessary news entries (it explains when you should(n't) add one).

StanFromIreland · 2026-06-21T09:13:39Z

+
+   .. code-block:: shell
+
+      ./python.exe -m test -j8


Similarly here, why the difference? We can pass -j0 here.

hugovk · 2026-06-21T09:49:29Z

+Here are the basic steps needed to get set up and open a pull request.
+
+This is meant as a checklist and cheat-sheet, not a comprehensive guide.
+For complete instructions please see the :ref:`setup guide <setup>` and the


We don't need "please" in technical docs

Suggested change

For complete instructions please see the :ref:`setup guide <setup>` and the

For complete instructions see the :ref:`setup guide <setup>` and the

hugovk · 2026-06-21T09:49:42Z

+
+.. note::
+
+   In order to keep the commit history intact, please avoid squashing or amending


Suggested change

In order to keep the commit history intact, please avoid squashing or amending

In order to keep the commit history intact, avoid squashing or amending

hugovk · 2026-06-21T09:50:10Z

+Setup Git
+=========


Suggested change

Setup Git

=========

Set up Git

==========

hugovk · 2026-06-21T09:50:42Z

+Create pull requests
+--------------------
+
+Create pull bequests on GitHub from your branches, on your fork, and make sure


Suggested change

Create pull bequests on GitHub from your branches, on your fork, and make sure

Create pull requests on GitHub from your branches, on your fork, and make sure

hugovk · 2026-06-21T09:54:04Z

+
+   .. code-block:: shell
+
+      ./configure --config-cache --with-pydebug && make -j8


It depends on the make command. With GNU make:

-j [jobs], --jobs[=jobs] Specifies the number of jobs (commands) to run simultaneously. If there is more than one -j option, the last one is effective. If the -j option is given without an argument, make will not limit the number of jobs that can run simultaneously.

"Don't limit" isn't the same as "use all available".

StanFromIreland reviewed Jun 14, 2026

View reviewed changes

hugovk reviewed Jun 14, 2026

View reviewed changes

willingc reviewed Jun 15, 2026

View reviewed changes

sirosen and others added 5 commits June 17, 2026 18:26

Change "Quick reference" to sentence-case

543e002

Co-authored-by: Hugo van Kemenade <[email protected]>

Replace the PR quickguide with a link

5e7e09e

Instead of a duplicate guide, we can now link to the canonical quick reference doc.

Restore a "continuity" quick-reference section

86f942c

In the index, ensure that anyone going to the old quick-reference documentation will find a short explanatory note and a link to the new, rehomed quick-reference.

StanFromIreland reviewed Jun 21, 2026

View reviewed changes

hugovk reviewed Jun 21, 2026

View reviewed changes


		PCbuild\build.bat -e -d

		See also :ref:`more detailed instructions <compiling>`,


		.\python.bat -m test -j3

		5. Create a new branch where your work for the issue will go, for example::


		.. code-block:: shell

		./configure --config-cache --with-pydebug && make -j8

	For complete instructions please see the :ref:`setup guide <setup>` and the
	For complete instructions see the :ref:`setup guide <setup>` and the


		.. note::

		In order to keep the commit history intact, please avoid squashing or amending

	Create pull bequests on GitHub from your branches, on your fork, and make sure
	Create pull requests on GitHub from your branches, on your fork, and make sure

Uh oh!

Conversation

sirosen commented Jun 13, 2026

Uh oh!

read-the-docs-community Bot commented Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirosen commented Jun 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

read-the-docs-community Bot commented Jun 13, 2026 •

edited

Loading