Fix all references

advanced-tools/clang.rst

@@ -1,3 +1,5 @@
+.. _clang:
+
 ***************************
 Dynamic Analysis with Clang
 ***************************

advanced-tools/coverity.rst

@@ -1,9 +1,9 @@
+.. _coverity:
+
 =============
 Coverity Scan
 =============
 
-.. _coverity:
-
 Coverity Scan is a free service for static code analysis of Open Source
 projects. It is based on Coverity's commercial product and is able to analyze
 C, C++ and Java code.

appendix.rst

@@ -6,65 +6,65 @@ Basics for contributors
 
 .. note:: **Recommended reading**
 
-   - :doc:`setup`
-   - :doc:`pullrequest`
+   - :doc:`starting/setup`
+   - :doc:`starting/pullrequest`
 
-* :doc:`help`
-* :doc:`communication`
+* :doc:`starting/help`
+* :doc:`developing/communication`
 
 Core developers
 ---------------
 
 .. note:: **Recommended reading**
 
-   * :doc:`setup`
-   * :doc:`pullrequest`
-   * :doc:`committing`
+   * :doc:`starting/setup`
+   * :doc:`starting/pullrequest`
+   * :doc:`committing/committing`
 
-* :doc:`coredev`
-* :doc:`developers`
-* :doc:`motivations`
-* :doc:`experts`
+* :doc:`committing/coredev`
+* :doc:`committing/developers`
+* :doc:`committing/motivations`
+* :doc:`triaging/experts`
 
 Development workflow for contributors
 -------------------------------------
 
-* :doc:`devcycle`
-* :doc:`pullrequest`
-* :doc:`fixingissues`
+* :doc:`developing/devcycle`
+* :doc:`starting/pullrequest`
+* :doc:`starting/fixingissues`
 
 Documenting Python and style guide
 ----------------------------------
 
-* :doc:`docquality`
-* :doc:`documenting`
+* :doc:`documenting/docquality`
+* :doc:`documenting/documenting`
 
 Issue tracking and triaging
 ---------------------------
 
-* :doc:`tracker`
-* :doc:`triaging`
-* :doc:`gh-labels`
-* :doc:`gh-faq`
+* :doc:`triaging/tracker`
+* :doc:`triaging/triaging`
+* :doc:`triaging/gh-labels`
+* :doc:`triaging/gh-faq`
 
 Language development in depth
 -----------------------------
 
-* :doc:`exploring`
-* :doc:`grammar`
-* :doc:`compiler`
-* :doc:`garbage_collector`
-* :doc:`stdlibchanges`
-* :doc:`langchanges`
-* :doc:`porting`
+* :doc:`exploring/exploring`
+* :doc:`developing/grammar`
+* :doc:`exploring/compiler`
+* :doc:`exploring/garbage_collector`
+* :doc:`developing/stdlibchanges`
+* :doc:`developing/langchanges`
+* :doc:`developing/porting`
 
 Testing and continuous integration
 ----------------------------------
 
-* :doc:`runtests`
-* :doc:`coverage`
-* :doc:`silencewarnings`
-* :doc:`buildbots`
-* :doc:`buildworker`
-* :doc:`coverity`
+* :doc:`testing/runtests`
+* :doc:`testing/coverage`
+* :doc:`testing/silencewarnings`
+* :doc:`testing/buildbots`
+* :doc:`testing/buildworker`
+* :doc:`tooling/coverity`
 

developer-workflow/communication-channels.rst

@@ -92,6 +92,8 @@ RSS feed readers.
 .. _web gateway: https://mail.python.org/archives/
 
 
+.. _discourse_discuss:
+
 Discourse (discuss.python.org web forum)
 ----------------------------------------
 

developer-workflow/grammar.rst

@@ -48,7 +48,7 @@ Note: sometimes things mysteriously don't work.  Before giving up, try ``make cl
 * :file:`Python/ast_unparse.c` will need changes to unparse AST objects involved with the
   grammar change ("unparsing" is used to turn annotations into strings per :pep:`563`).
 
-* The :doc:`compiler` has its own page.
+* The :ref:`compiler` has its own page.
 
 * ``_Unparser`` in the :file:`Lib/ast.py` file may need changes to accommodate
   any modifications in the AST nodes.

documentation/help-documenting.rst

@@ -57,7 +57,7 @@ If you see a documentation issue that you would like to tackle, you can:
 * leave a comment on the issue saying you are going to try and create a pull
   request and roughly how long you think you will take to do so (this allows
   others to take on the issue if you happen to forget or lose interest).
-* submit a :doc:`pull request <pullrequest>` for the issue.
+* submit a :ref:`pull request <pullrequest>` for the issue.
 
 By following the steps in the :ref:`Quick Guide to Pull Requests <pullrequest-quickguide>`,
 you will learn the workflow for documentation pull requests.
@@ -104,7 +104,7 @@ published in the release.
 Developer's Guide workflow
 --------------------------
 
-To submit a :doc:`pull request <pullrequest>`, you can fork the
+To submit a :ref:`pull request <pullrequest>`, you can fork the
 `devguide repo`_ to your GitHub account and clone it using::
 
     $ git clone https://github.com/<your_username>/devguide
@@ -129,7 +129,7 @@ in the checkout directory.  On Windows use:
 You will find the generated files in ``_build/html`` or, if you use
 ``make htmlview``, the docs will be opened in a browser once the build
 completes.  Note that ``make check`` runs automatically when you submit
-a :doc:`pull request <pullrequest>`.  You may wish to run ``make check``
+a :ref:`pull request <pullrequest>`.  You may wish to run ``make check``
 and ``make linkcheck`` to make sure that it runs without errors.
 
 .. _separate repository:

documentation/start-documenting.rst

@@ -1550,7 +1550,7 @@ build completes.
 
 You can also use ``make help`` to see a list of targets supported by
 :command:`make`.  Note that ``make check`` is automatically run when
-you submit a :doc:`pull request <pullrequest>`, so you should make
+you submit a :ref:`pull request <pullrequest>`, so you should make
 sure that it runs without errors.
 
 **On Windows**, a :file:`make.bat` batchfile tries to emulate :command:`make`

getting-started/getting-help.rst

@@ -15,7 +15,7 @@ question.
 Discourse
 ---------
 
-Python has a hosted `Discourse`_ instance. This forum has many different
+Python has a hosted :ref:`Discourse <discourse_discuss>` instance. This forum has many different
 categories and most core development discussions take place in the open forum
 categories for `PEPs`_ and `Core Development`_ .
 Most categories are open for all users to read and post with the exception of
@@ -25,7 +25,7 @@ categories, such as
 `Core Workflow <https://discuss.python.org/c/core-workflow/8>`_.
 
 .. seealso::
-  `Discourse <https://devguide.python.org/communication/#discourse-discuss-python-org-web-forum>`_
+  :ref:`Discourse <discourse_discuss>`
   on how to get started.
 
 

getting-started/git-boot-camp.rst

@@ -184,6 +184,8 @@ rename your local branch as follows::
     git branch -u upstream/main main
 
 
+.. _commit-changes:
+
 Staging and Committing Files
 ----------------------------
 

getting-started/pull-request-lifecycle.rst

@@ -1,4 +1,5 @@
 .. _patch:
+.. _pullrequest:
 
 Lifecycle of a Pull Request
 ===========================
@@ -89,7 +90,7 @@ You should have already :ref:`set up your system <setup>`,
      make patchcheck
      ./python -m test
 
-  (Learn more about :ref:`patchcheck` and about :doc:`runtests`)
+  (Learn more about :ref:`patchcheck` and about :ref:`runtests`)
 
 * Once you are satisfied with the changes, add the files and commit them::
 

index.rst

@@ -42,7 +42,7 @@ instructions please see the :ref:`setup guide <setup>`.
    and the platform-specific pages for :ref:`UNIX <unix-compiling>`,
    :ref:`Mac OS <MacOS>`, and :ref:`Windows <windows-compiling>`.
 
-4. :doc:`Run the tests <runtests>`::
+4. :ref:`Run the tests <runtests>`::
 
       ./python -m test -j3
 
@@ -60,7 +60,7 @@ instructions please see the :ref:`setup guide <setup>`.
 6. Once you fixed the issue, run the tests, run ``make patchcheck``, and if
    everything is ok, commit.
 
-7. Push the branch on your fork on GitHub and :doc:`create a pull request
+7. Push the branch on your fork on GitHub and :ref:`create a pull request
    <pullrequest>`.  Include the issue number using ``gh-NNNN`` in the
    pull request description.  For example::
 
@@ -85,9 +85,9 @@ contributing to Python:
 
 * `Issue tracker`_
 * `Buildbot status`_
-* :doc:`help`
+* :ref:`help`
 * PEPs_ (Python Enhancement Proposals)
-* :doc:`gitbootcamp`
+* :ref:`gitbootcamp`
 
 .. _branchstatus:
 
@@ -159,29 +159,29 @@ Guide for contributing to Python:
 +------------------------+---------------------+-----------------------+---------------------+
 | New Contributors       | Documentarians      | Triagers              | Core Developers     |
 +========================+=====================+=======================+=====================+
-| :doc:`setup`           | :doc:`docquality`   | :doc:`tracker`        | :doc:`coredev`      |
+| :ref:`setup`           | :ref:`docquality`   | :ref:`tracker`        | :ref:`coredev`      |
 +------------------------+---------------------+-----------------------+---------------------+
-| :doc:`help`            | :doc:`documenting`  | :doc:`triaging`       | :doc:`developers`   |
+| :ref:`help`            | :ref:`documenting`  | :ref:`triaging`       | :ref:`developers`   |
 +------------------------+---------------------+-----------------------+---------------------+
-| :doc:`pullrequest`     | :ref:`style-guide`  | :ref:`helptriage`     | :doc:`committing`   |
+| :ref:`pullrequest`     | :ref:`style-guide`  | :ref:`helptriage`     | :ref:`committing`   |
 +------------------------+---------------------+-----------------------+---------------------+
-| :doc:`runtests`        | :ref:`rst-primer`   | :doc:`experts`        | :doc:`devcycle`     |
+| :ref:`runtests`        | :ref:`rst-primer`   | :ref:`experts`        | :ref:`devcycle`     |
 +------------------------+---------------------+-----------------------+---------------------+
-| :doc:`fixingissues`    | :ref:`translating`  |                       | :doc:`motivations`  |
+| :ref:`fixingissues`    | :ref:`translating`  |                       | :ref:`motivations`  |
 +------------------------+---------------------+-----------------------+---------------------+
-| :doc:`communication`   |                     |                       | :ref:`office hour`  |
+| :ref:`communication`   |                     |                       | :ref:`office hour`  |
 +------------------------+---------------------+-----------------------+---------------------+
-| :doc:`gitbootcamp`     |                     |                       |                     |
+| :ref:`gitbootcamp`     |                     |                       |                     |
 +------------------------+---------------------+-----------------------+---------------------+
 
 Advanced tasks and topics for once you are comfortable:
 
-* :doc:`silencewarnings`
-* Fixing issues found by the :doc:`buildbots <buildbots>`
-* :doc:`coverity`
+* :ref:`silencewarnings`
+* Fixing issues found by the :ref:`buildbots <buildbots>`
+* :ref:`coverity`
 * Helping out with reviewing `open pull requests`_.
   See :ref:`how to review a Pull Request <how-to-review-a-pull-request>`.
-* :doc:`fixingissues`
+* :ref:`fixingissues`
 
 It is **recommended** that the above documents be read as needed. New
 contributors will build understanding of the CPython workflow by reading the
@@ -206,8 +206,8 @@ developer's toolkit.
 While these kinds of change are much rarer than those described above, they do
 happen and that process is also described as part of this guide:
 
-* :doc:`stdlibchanges`
-* :doc:`langchanges`
+* :ref:`stdlibchanges`
+* :ref:`langchanges`
 
 
 Other Interpreter Implementations
@@ -242,15 +242,15 @@ Key Resources
 * `Issue tracker`_
     * `Meta tracker <https://issues.roundup-tracker.org/>`_ (issue
       tracker for the issue tracker)
-    * :doc:`experts`
+    * :ref:`experts`
 * `Buildbot status`_
 * Source code
     * `Browse online <https://github.com/python/cpython/>`_
     * `Snapshot of the *main* branch <https://github.com/python/cpython/archive/main.zip>`_
     * `Daily OS X installer <https://buildbot.python.org/daily-dmg/>`_
 * PEPs_ (Python Enhancement Proposals)
-* :doc:`help`
-* :doc:`developers`
+* :ref:`help`
+* :ref:`developers`
 
 
 .. _resources:
@@ -261,14 +261,14 @@ Additional Resources
 * Anyone can clone the sources for this guide.  See
   :ref:`helping-with-the-developers-guide`.
 * Help with ...
-    * :doc:`exploring`
-    * :doc:`grammar`
-    * :doc:`parser`
-    * :doc:`compiler`
-    * :doc:`garbage_collector`
+    * :ref:`exploring`
+    * :ref:`grammar`
+    * :ref:`parser`
+    * :ref:`compiler`
+    * :ref:`garbage_collector`
 * Tool support
-    * :doc:`gdb`
-    * :doc:`clang`
+    * :ref:`gdb`
+    * :ref:`clang`
     * Various tools with configuration files as found in the `Misc directory`_
     * Information about editors and their configurations can be found in the
       `wiki <https://wiki.python.org/moin/PythonEditors>`_

internals/compiler.rst

@@ -34,7 +34,7 @@ The grammar file for Python can be found in
 :file:`Grammar/python.gram`.  The definitions for literal tokens
 (such as ``:``, numbers, etc.) can be found in :file:`Grammar/Tokens`.
 Various C files, including :file:`Parser/parser.c` are generated from
-these (see :doc:`grammar`).
+these (see :ref:`grammar`).
 
 
 Abstract Syntax Trees (AST)

internals/garbage-collector.rst

@@ -1,4 +1,5 @@
 .. _gc:
+.. _garbage_collector:
 
 Design of CPython's Garbage Collector
 =====================================

testing/buildbots.rst

@@ -5,7 +5,7 @@ Continuous Integration
 
 .. highlight:: bash
 
-To assert that there are no regressions in the :doc:`development and maintenance
+To assert that there are no regressions in the :ref:`development and maintenance
 branches <devcycle>`, Python has a set of dedicated machines (called *buildbots*
 or *build workers*) used for continuous integration.  They span a number of
 hardware/operating system combinations.  Furthermore, each machine hosts
@@ -105,7 +105,7 @@ introducing additional failures should generally not be an option.
 Flags-dependent failures
 ------------------------
 
-Sometimes, while you have run the :doc:`whole test suite <runtests>` before
+Sometimes, while you have run the :ref:`whole test suite <runtests>` before
 committing, you may witness unexpected failures on the buildbots.  One source
 of such discrepancies is if different flags have been passed to the test runner
 or to Python itself.  To reproduce, make sure you use the same flags as the

testing/coverage.rst

@@ -258,7 +258,7 @@ times.
 Filing the Issue
 """"""""""""""""
 Once you have increased coverage, you need to create an issue on the
-`issue tracker`_ and submit a :doc:`pull request <pullrequest>`. On the
+`issue tracker`_ and submit a :ref:`pull request <pullrequest>`. On the
 issue set the "Components" to "Test" and "Versions" to the version of Python you
 worked on (i.e., the in-development version).
 

triage/github-bpo-faq.rst

@@ -1,11 +1,13 @@
+.. _gh-faq:
+
 GitHub issues for BPO users
 ===========================
 
 Here are some frequently asked questions about how to do things in
 GitHub issues that you used to be able to do on `bpo`_.
 
-Before you ask your own question, make sure you read :doc:`tracker`
-and :doc:`triaging` (specifically including :doc:`gh-labels`) as those
+Before you ask your own question, make sure you read :ref:`tracker`
+and :ref:`triaging` (specifically including :ref:`gh-labels`) as those
 pages include a lot of introductory material.
 
 How to format my comments nicely?