diff --git a/contrib/intro/index.rst b/contrib/intro/index.rst index c5ba303dfd..98fa30fc38 100644 --- a/contrib/intro/index.rst +++ b/contrib/intro/index.rst @@ -24,12 +24,12 @@ Python is an open source project, with culture and techniques from the broader open source world. You might find it helpful to read about open source in general. A number of individuals from the Python community have contributed to a series of excellent guides at `Open Source Guides -`_. +`__. Anyone will find the following guides useful: -* `How to Contribute to Open Source `_ -* `Building Welcoming Communities `_ +* `How to Contribute to Open Source `__ +* `Building Welcoming Communities `__ Healthy collaboration diff --git a/core-team/committing.rst b/core-team/committing.rst index 41cf672542..a88ff12053 100644 --- a/core-team/committing.rst +++ b/core-team/committing.rst @@ -59,11 +59,11 @@ to enter the public source tree. Ask yourself the following questions: * **Does the pull request pass a check indicating that the submitter has signed the CLA?** Make sure that the contributor has signed a `Contributor - Licensing Agreement `_ + Licensing Agreement `__ (CLA), unless their change has no possible intellectual property associated with it (for example, fixing a spelling mistake in documentation). The `Python Software Foundation Contributor License Agreement Management Bot - `_ + `__ checks whether the author has signed the CLA, and replies in the PR if they haven't. For further questions about the CLA process, write to contributors@python.org. @@ -125,7 +125,7 @@ How to add a NEWS entry ^^^^^^^^^^^^^^^^^^^^^^^ ``NEWS`` entries go into the ``Misc/NEWS.d`` directory as individual files. The -``NEWS`` entry can be created by using `blurb-it `_, +``NEWS`` entry can be created by using `blurb-it `__, or the :pypi:`blurb` tool and its ``blurb add`` command. If you are unable to use the tool, then you can create the ``NEWS`` entry file diff --git a/core-team/experts.rst b/core-team/experts.rst index 2fb37cb3f9..01935106ba 100644 --- a/core-team/experts.rst +++ b/core-team/experts.rst @@ -365,6 +365,6 @@ Documentation translations ========================== Translations are within the charter of -`Editorial Board `_. +`Editorial Board `__. For a list of translations and their coordinators, see :ref:`this table of translations `. diff --git a/core-team/join-team.rst b/core-team/join-team.rst index d7996cd424..20ce9e4c98 100644 --- a/core-team/join-team.rst +++ b/core-team/join-team.rst @@ -40,14 +40,14 @@ are granted through these steps: (as per :pep:`13`), the submitter `emails the steering council `_ with the candidate's email address requesting that the council either accept or reject the proposed membership. Technically, the - council may only `veto a positive vote `_. + council may only `veto a positive vote `__. #. Assuming the steering council does not veto the positive vote, a member of the council or its delegate (approver, usually in practice a :ref:`Developer-in-Residence `) will email the candidate: - A request for account details as required by - `🔒 python/voters `_. + `🔒 python/voters `__. - A reminder about the `Code of Conduct`_ and guidance on reporting issues to the PSF Conduct WG. @@ -55,12 +55,12 @@ are granted through these steps: - Enable the various new privileges. - Remove the new committer from the triage team, if applicable. - - Add their details to `🔒 python/voters `_. + - Add their details to `🔒 python/voters `__. - Once the python/voters update is merged, regenerate the public team membership list at :ref:`developers`. See "Public list of members" in the ``voters`` README. - Post an announcement in the `Committers Discourse category - `_. The past few announcements + `__. The past few announcements were in the form of a separate post on the already open topic with the poll. @@ -69,7 +69,7 @@ Getting a python.org email address Members of the core team can get an email address on the python.org domain. For more details refer to the `python.org email policy -`_. +`__. Poll template diff --git a/core-team/memorialization.rst b/core-team/memorialization.rst index 7ab0fab02b..3d893a3029 100644 --- a/core-team/memorialization.rst +++ b/core-team/memorialization.rst @@ -31,11 +31,11 @@ certain content when the legacy contact or family members request it. GitHub ------ -* The user is removed from the `python/ `_ +* The user is removed from the `python/ `__ organization on GitHub; -* The user is removed from the `psf/ `_ +* The user is removed from the `psf/ `__ organization on GitHub; -* The user is removed from the `pypa/ `_ +* The user is removed from the `pypa/ `__ organization on GitHub. The PSF staff does not follow up with GitHub with regards to GitHub account @@ -43,7 +43,7 @@ cancellation as this action is reserved for next-of-kin or designated by the deceased GitHub user to act as an account successor. The general policy regarding deceased users on GitHub is described on their -`Deceased User Policy `_ +`Deceased User Policy `__ page. Repositories in the organization @@ -51,9 +51,9 @@ Repositories in the organization * The user's GitHub handle is removed from ``/.github/CODEOWNERS``. To see all that need action, perform - `this query `_. + `this query `__. * The user is marked as deceased in the private - `voters/python-core.toml `_ + `voters/python-core.toml `__ file with the ``left=`` field set to the day of passing, if known. discuss.python.org @@ -80,7 +80,7 @@ a community member close to the deceased. The general best practice for deceased community members on Discourse-powered forums is described on their -`Best practices for deceased community members `_ +`Best practices for deceased community members `__ page. python.org email account @@ -116,8 +116,8 @@ python.org admin devguide.python.org ------------------- -* The user is marked as deceased in `core-team.csv `_; -* The user is removed from the `experts index `_. +* The user is marked as deceased in `core-team.csv `__; +* The user is removed from the `experts index `__. bugs.python.org --------------- @@ -139,16 +139,16 @@ Other PSF-related infrastructure Discord server to remove the user from the server. The PSF staff does not follow up with Discord with regards to Discord account cancellation. The general policy regarding deceased users on Discord - is available on their `Deceased or Incapacitated Users `_ + is available on their `Deceased or Incapacitated Users `__ page. * The user is removed from Salt configuration for the PSF infrastructure - in `/pillar/base/users `_ + in `/pillar/base/users `__ that allows SSH access to PSF-controlled servers. * The user might have ran a buildbot worker. The PSF staff member will look for that in the - `buildmaster-config `_ + `buildmaster-config `__ repository. PyPI diff --git a/core-team/motivations.rst b/core-team/motivations.rst index 6d539b7c3b..d0e5a0cc18 100644 --- a/core-team/motivations.rst +++ b/core-team/motivations.rst @@ -97,13 +97,13 @@ participating in the CPython core development process: .. topic:: Brett Cannon (Canada) - * Personal site: `snarky.ca `_ + * Personal site: `snarky.ca `__ * Microsoft (Software Developer) * Python Software Foundation (Fellow) .. topic:: Alyssa Coghlan (Australia) - * Personal site: `Curious Efficiency `_ + * Personal site: `Curious Efficiency `__ * `Extended bio `__ * Python Software Foundation (Fellow, Packaging Working Group) * Westpac (Principal Python Engineer) @@ -123,9 +123,9 @@ participating in the CPython core development process: .. topic:: Steve Dower (United States/Australia) * Microsoft (Software Developer) - * Personal site: `stevedower.id.au `_ - * Speaking: `stevedower.id.au/speaking `_ - * Work blog: `devblogs.microsoft.com/python/ `_ + * Personal site: `stevedower.id.au `__ + * Speaking: `stevedower.id.au/speaking `__ + * Work blog: `devblogs.microsoft.com/python/ `__ * Email address: steve.dower@python.org Steve started with Python while automating a test harness for medical @@ -143,25 +143,25 @@ participating in the CPython core development process: .. topic:: Mariatta (Canada) - * Personal site: `mariatta.ca `_ - * Works as a `Software Engineer `_ + * Personal site: `mariatta.ca `__ + * Works as a `Software Engineer `__ in Vancouver, helps organize `Vancouver PyLadies - `_ meetup on the side, and - sometimes `speaks `_ + `__ meetup on the side, and + sometimes `speaks `__ at conferences. * Email address: mariatta@python.org - * `Sponsor Mariatta on GitHub `_ - * `Patreon `_ + * `Sponsor Mariatta on GitHub `__ + * `Patreon `__ - Support Mariatta by `becoming a sponsor `_, - sending her a `happiness packet `_, - or `paypal `_. + Support Mariatta by `becoming a sponsor `__, + sending her a `happiness packet `__, + or `paypal `__. .. topic:: R. David Murray (United States) - * Personal site: `bitdance.com `_ + * Personal site: `bitdance.com `__ * Available for `Python and Internet Services Consulting - and Python contract programming `_ + and Python contract programming `__ David has been involved in the Internet since the days when the old IBM BITNET and the ARPANet got cross connected, and in Python programming since @@ -177,7 +177,7 @@ participating in the CPython core development process: David currently does both proprietary and open source development work, primarily in Python, through the company in which he is a partner, `Murray & - Walker, Inc `_. He has done contract work + Walker, Inc `__. He has done contract work focused specifically on CPython development both through the PSF (the kickstart of the email Unicode API development) and directly funded by interested corporations (additional development work on email funded by @@ -187,7 +187,7 @@ participating in the CPython core development process: .. topic:: Antoine Pitrou (France) - * LinkedIn: ``_ (Senior Software Engineer) + * LinkedIn: ``__ (Senior Software Engineer) * QuantStack * Python Software Foundation (Fellow) * Email address: antoine@python.org @@ -213,7 +213,7 @@ participating in the CPython core development process: Victor is paid by Red Hat to maintain Python upstream and downstream (RHEL, CentOS, Fedora & Software collections). See `Victor's contributions to - Python `_. + Python `__. .. topic:: Kushal Das (India) @@ -224,21 +224,21 @@ participating in the CPython core development process: .. topic:: Barry Warsaw (United States) * NVIDIA, Principal System Software Engineer, Open Source Python Ecosystem - * Personal site: `barry.warsaw.us `_ - * Blog: `We Fear Change `_ - * `LinkedIn `_ - * `Bluesky `_ + * Personal site: `barry.warsaw.us `__ + * Blog: `We Fear Change `__ + * `LinkedIn `__ + * `Bluesky `__ * Email address: barry@python.org * Python Software Foundation (Fellow) Barry has been working in, with, and on Python since 1994. He attended the - first Python workshop at `NIST `_ in Gaithersburg, + first Python workshop at `NIST `__ in Gaithersburg, MD in 1994, where he met Guido and several other early Python adopters. Barry subsequently worked with Guido for 8 years while at `CNRI - `_. Barry has served as Python's postmaster, + `__. Barry has served as Python's postmaster, webmaster, release manager, Language Summit co-chair, `Jython - `_ project leader, `GNU Mailman - `_ project leader, and Python Steering Council + `__ project leader, `GNU Mailman + `__ project leader, and Python Steering Council member in 2019, 2020, 2021, 2024, and 2025. .. topic:: Eric Snow (United States) @@ -256,13 +256,13 @@ participating in the CPython core development process: developers on the project for 6 years. After that he started the Python Tools for Visual Studio project focusing on providing advanced code completion and debugging features for Python. Today he works on - `Cinder `_ improving Python + `Cinder `__ improving Python performance for Instagram. .. topic:: Carol Willing (United States) * Noteable (VP Engineering) - * Personal site: `Willing Consulting `_ + * Personal site: `Willing Consulting `__ * `Extended bio `__ * Project Jupyter (Software Council, Core Team for JupyterHub/Binder) * Python Software Foundation (Fellow) diff --git a/core-team/responsibilities.rst b/core-team/responsibilities.rst index 3b2137d6b0..9f5c62b728 100644 --- a/core-team/responsibilities.rst +++ b/core-team/responsibilities.rst @@ -48,12 +48,12 @@ Communication channels and bug notifications ============================================ Mailing lists have generally been replaced by the -`Discourse forum `_ (``discuss.python.org``). +`Discourse forum `__ (``discuss.python.org``). Refer to the :ref:`mailinglists` and :ref:`communication-discourse` sections for more information. If you want notification of new issues, you can use the appropriate GitHub notification -settings for the `python/cpython `_ repository — +settings for the `python/cpython `__ repository — follow the link and click on the :guilabel:`Watch` button to set your notification options. diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index 90c1d12e4e..c65e88ce1c 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -38,7 +38,7 @@ While internal API can be changed at any time, it's still good to keep it stable: other API or other CPython developers may depend on it. For users, internal API is sometimes the best workaround for a thorny problem --- though those use cases should be discussed on the -`C API Discourse category `_ +`C API Discourse category `__ or an issue so we can try to find a supported way to serve them. @@ -218,7 +218,7 @@ use this API reliably: (:samp:`3.{x}.0`, including Alphas and Betas for :samp:`3.{x}.0`). * Adding a new unstable API *for an existing feature* is allowed even after Beta feature freeze, up until the first Release Candidate. - Consensus on the `Core Development Discourse `_ + Consensus on the `Core Development Discourse `__ is needed in the Beta period. * Backwards-incompatible changes should make existing C callers fail to compile. For example, arguments should be added/removed, or a function should be diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 9b088b350e..43c00b9e1b 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -64,7 +64,7 @@ core development workflow. A complete list of Python mailing lists can be found at https://mail.python.org/mailman/listinfo (older lists, using Mailman2) or https://mail.python.org/mailman3/ (newer lists, using Mailman3). Some lists may also -be mirrored at `GMANE `_ and can be read and posted to in various +be mirrored at `GMANE `__ and can be read and posted to in various ways, including via web browsers, NNTP newsreaders, and RSS feed readers. .. _python-list: https://mail.python.org/mailman/listinfo/python-list @@ -84,7 +84,7 @@ take place in the open forum categories for `PEPs`_ and `Core Development`_ (these are the Discourse equivalents to the python-dev mailing list). All categories are open for users to read and post with the exception of the `Committers`_ category, where posting is restricted to the `CPython -`_ core team. +`__ core team. The Committers category is often used for announcements and notifications. It is also the designated venue for the core team promotion votes. @@ -97,8 +97,8 @@ create an account using an email address or GitHub account. You can do so by clicking the :guilabel:`Sign Up` button on the top right hand corner of the `Discourse`_ main page. -The Python Discourse `Quick Start `_ -compiled by `Carol Willing `_ gives you +The Python Discourse `Quick Start `__ +compiled by `Carol Willing `__ gives you a quick overview on how to kick off Python Discourse. We recommend new users getting familiarised with the forum by going through Discobot tutorials. @@ -114,13 +114,13 @@ Greetings!" received under Notifications and Messages in your user account. * Select either Notifications or Messages. * Open the "Greetings!" message sent by Discobot to start the tutorial. -Ensure that you read through the `Python Code of Conduct `_. +Ensure that you read through the `Python Code of Conduct `__. We are to be open, considerate and respectful to all users in the community. You can report messages that don't respect the CoC by clicking on the three dots under the message and then on the :guilabel:`⚐` icon. You can also mention the -`@staff `_, -`@moderators `_, or -`@admins `_ groups in a message. +`@staff `__, +`@moderators `__, or +`@admins `__ groups in a message. @@ -164,7 +164,7 @@ Customising notifications on user preference ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To get a bird's eye view of all your customised notifications, you can -go to `Preferences of your account `_. +go to `Preferences of your account `__. This allows you to make adjustments according to categories, users, and tags. Enabling mailing list mode @@ -174,7 +174,7 @@ In mailing list mode, you will receive one email per post, as happens with traditional mailing lists. This is desirable if you prefer to interact via email, without visiting the forum website. To activate the mailing list mode, go to the `email preferences -`_, check "Enable +`__, check "Enable mailing list mode" and save changes. .. _Discourse: https://discuss.python.org/ @@ -243,7 +243,7 @@ Setting expectations for open source participation ================================================== Burn-out is common in open source due to a misunderstanding of what users, contributors, -and maintainers should expect from each other. Brett Cannon gave a `talk `_ +and maintainers should expect from each other. Brett Cannon gave a `talk `__ about this topic that sets out to help everyone set reasonable expectations of each other in order to make open source pleasant for everyone involved. diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 7f82ea42f0..d39fd2cfc5 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -134,7 +134,7 @@ former branch, for example, ``3.8`` or ``2.7``. The :ref:`versions` page contains list of active and end-of-life branches. The latest release for each Python version can be found on the `download page -`_. +`__. .. _stages: @@ -212,27 +212,27 @@ Repository administration ------------------------- The source code is currently hosted on `GitHub -`_ in the `Python organization `_. +`__ in the `Python organization `__. Organization repository policy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Within the `GitHub Python organization `_, +Within the `GitHub Python organization `__, repositories are expected to relate to the Python language, the CPython reference implementation, their documentation and their development workflow. This includes, for example: -* The reference implementation of Python and related repositories: `CPython `_. -* Tooling and support around CPython development: `pyperformance `_, `Bedevere `_. -* Helpers and backports for Python/CPython features: `typing_extensions `_, `typeshed `_, `tzdata `_, `pythoncapi-compat `_. -* Organization-related repositories: the `Code of Conduct `_, `.github `_. -* Documentation and websites for all the above: `python.org repository `_, `PEPs `_, `Devguide `_, docs translations. -* Infrastructure for all the above: `docsbuild-scripts `_, `buildmaster-config `_. -* Discussions and notes around official development-related processes and events: `steering-council `_, `core-sprint `_. +* The reference implementation of Python and related repositories: `CPython `__. +* Tooling and support around CPython development: `pyperformance `__, `Bedevere `__. +* Helpers and backports for Python/CPython features: `typing_extensions `__, `typeshed `__, `tzdata `__, `pythoncapi-compat `__. +* Organization-related repositories: the `Code of Conduct `__, `.github `__. +* Documentation and websites for all the above: `python.org repository `__, `PEPs `__, `Devguide `__, docs translations. +* Infrastructure for all the above: `docsbuild-scripts `__, `buildmaster-config `__. +* Discussions and notes around official development-related processes and events: `steering-council `__, `core-sprint `__. Before adding a new repository to the organization, open a discussion to seek consensus -in the `Committers Discourse category `_. -Once people are satisfied with that, ask the `Python steering council `_ +in the `Committers Discourse category `__. +Once people are satisfied with that, ask the `Python steering council `__ to grant permission. Note that several repositories remain in the organization for historic reasons, @@ -241,18 +241,18 @@ and would probably not be appropriate to add today. Generally, new repositories should start their life under personal GitHub accounts or other GitHub orgs. It is relatively easy to move a repository to the organization once it is mature. For example, this would now apply to -experimental features like `asyncio `_, -`exceptiongroups `_, +experimental features like `asyncio `__, +`exceptiongroups `__, and drafts of new guides and other documentation (for example, `redistributor-guide -`_). +`__). -General-use tools and libraries (for example, `mypy `_ -or `Black `_) should also be developed outside +General-use tools and libraries (for example, `mypy `__ +or `Black `__) should also be developed outside the ``python`` organization, unless core devs (as represented by the SC) specifically want to “bless” one implementation (as with -`typeshed `_, -`tzdata `_, or -`pythoncapi-compat `_). +`typeshed `__, +`tzdata `__, or +`pythoncapi-compat `__). Organization owner policy @@ -264,7 +264,7 @@ at all levels including organization membership, team membership, access control, and merge privileges on all repositories. For full details of the permission levels see `GitHub's documentation on Organization permission levels -`_. +`__. This role is paramount to the security of the Python Language, Community, and Infrastructure. @@ -315,7 +315,7 @@ The Administrator role on the repository allows for managing all aspects including collaborators, access control, integrations, webhooks, and branch protection. For full details of the permission levels see `GitHub's documentation on repository permission levels -`_. +`__. Common reasons for this role are: maintenance of core workflow tooling, Release Managers for all :ref:`in-development `, :ref:`maintenance `, and :ref:`security mode ` diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index 7131cfdf86..fa4c11868f 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -562,7 +562,7 @@ Now that the configuration is in place, it remains to compile the project: .. tip:: - We recommend installing `Podman `_ + We recommend installing `Podman `__ instead of Docker since the former does not require a background service and avoids creating files owned by the ``root`` user in some cases. @@ -609,8 +609,8 @@ by executing :cpy-file:`Tools/build/regen-configure.sh`: If Docker complains about missing permissions, this Stack Overflow post could be useful in solving the issue: `How to fix docker: permission denied -`_. Alternatively, you may try -using `Podman `_. +`__. Alternatively, you may try +using `Podman `__. Missing ``Py_BUILD_CORE`` define when using internal headers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/developer-workflow/grammar.rst b/developer-workflow/grammar.rst index d574dfed7d..bd314c61e3 100644 --- a/developer-workflow/grammar.rst +++ b/developer-workflow/grammar.rst @@ -5,4 +5,4 @@ Changing CPython's grammar ========================== This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/developer-workflow/sbom.rst b/developer-workflow/sbom.rst index 756c175708..c8a2facd14 100644 --- a/developer-workflow/sbom.rst +++ b/developer-workflow/sbom.rst @@ -5,15 +5,15 @@ Software Bill-of-Materials (abbreviated as "SBOM") is a document for sharing information about software and how it's been composed. This format is used most often in the security space for checking software and its dependencies for vulnerabilities using vulnerability databases like -`CVE `_ and `OSV `_. The SBOM format -that the CPython project uses is `SPDX `_ +`CVE `__ and `OSV `__. The SBOM format +that the CPython project uses is `SPDX `__ which can be transformed into other formats if necessary by consumers. There are multiple sources of third-party dependencies for CPython. Some are vendored into the source code of CPython itself (like ``mpdecimal`` vendored at :cpy-file:`Modules/_decimal/libmpdec`) or they could be optionally pulled in during builds like Windows using dependencies from the -`python/cpython-source-deps `_ +`python/cpython-source-deps `__ repository. Whenever adding or updating a third-party dependency, an update will likely @@ -51,10 +51,10 @@ Adding a new dependency When adding a dependency it's important to have the following information: * Name, version, and download URL of the project -* License of the project as an `SPDX License Expression `_ +* License of the project as an `SPDX License Expression `__ * Software identifiers that match values in vulnerability databases - (`CPE `_ and - `Package URLs `_ + (`CPE `__ and + `Package URLs `__ or "PURLs") * Paths to include and exclude in the CPython source tree corresponding to this dependency diff --git a/development-tools/clang.rst b/development-tools/clang.rst index b353d82f00..149fb7adcf 100644 --- a/development-tools/clang.rst +++ b/development-tools/clang.rst @@ -11,7 +11,7 @@ libraries. This document does not cover interpreting the findings. For a discussion of interpreting results, see Marshall Clow's `Testing libc++ with --fsanitize=undefined `_. The +-fsanitize=undefined `__. The blog posting is a detailed examinations of issues uncovered by Clang in ``libc++``. @@ -45,7 +45,7 @@ flags are passed through ``CFLAGS`` and ``CXXFLAGS``, and sometimes through ``CC`` and ``CXX`` (in addition to the compiler). A complete list of sanitizers can be found at `Controlling Code Generation -`_. +`__. .. note:: @@ -70,7 +70,7 @@ Pre-built Clang builds are available for most platforms: includes the "C++ clang tools for windows" feature. You can also build ``clang`` from source; refer to -`the clang documentation `_ for details. +`the clang documentation `__ for details. The installer does not install all the components needed on occasion. For example, you might want to run a ``scan-build`` or examine the results with @@ -284,6 +284,6 @@ Or, you could ignore the entire file with:: Unfortunately, you won't know what to ignorelist until you run the sanitizer. The documentation is available at `Sanitizer special case list -`_. +`__. .. _Valgrind: https://github.com/python/cpython/blob/main/Misc/README.valgrind diff --git a/development-tools/gdb.rst b/development-tools/gdb.rst index 8f89ea1360..835b2dbc70 100644 --- a/development-tools/gdb.rst +++ b/development-tools/gdb.rst @@ -29,7 +29,7 @@ this approach is less helpful when debugging the runtime virtual machine, since the main interpreter loop function, ``_PyEval_EvalFrameDefault``, is well over 4,000 lines long as of Python 3.12. Fortunately, among the `many ways to set breakpoints -`_, +`__, you can break at C labels, such as those generated for computed gotos. If you are debugging an interpreter compiled with computed goto support (generally true, certainly when using GCC), each instruction will be diff --git a/documentation/devguide.rst b/documentation/devguide.rst index 7c53d054e1..9f2ada23c1 100644 --- a/documentation/devguide.rst +++ b/documentation/devguide.rst @@ -23,7 +23,7 @@ Changes to the Developer's Guide are published when pull requests are merged. Changes to the Python documentation are published regularly, ususally within 48 hours of the change being committed. -The documentation is also `published for each release `_, +The documentation is also `published for each release `__, which may also be used by redistributors. diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 1c64b4832c..23520375cb 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -37,8 +37,8 @@ The in-development and recent maintenance branches are rebuilt once per day. If you would like to be more involved with documentation, consider subscribing to the `Documentation category on the Python Discourse -`_ and the -`docs@python.org `_ mailing list +`__ and the +`docs@python.org `__ mailing list where user issues are raised and documentation toolchain, projects, and standards are discussed. diff --git a/documentation/markup.rst b/documentation/markup.rst index cad0b4d9c3..f9291a335b 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -28,7 +28,7 @@ attribute definitions ``.. attribute: `attr-name``` :ref:`inform attribute references ``:attr:`attr-name``` :ref:`roles` reference labels ``.. _label-name:`` :ref:`doc-ref-role` internal references ``:ref:`label-name``` :ref:`doc-ref-role` -external links ```Link text `_`` :ref:`hyperlinks` +external links ```Link text `__`` :ref:`hyperlinks` roles w/ custom text ``:role:`custom text ``` :ref:`roles` roles w/ only last part ``:role:`~hidden.hidden.visible``` :ref:`roles` roles w/o link ``:role:`!target``` :ref:`roles` @@ -51,7 +51,7 @@ language, this will not take too long. .. seealso:: The authoritative `reStructuredText User - Documentation `_. + Documentation `__. Use of whitespace @@ -185,9 +185,12 @@ Hyperlinks External links ^^^^^^^^^^^^^^ -Use ```Link text `_`` for inline web links. If the link text +Use ```Link text `__`` for inline web links. If the link text should be the web address, you don't need special markup at all, the parser -finds links and mail addresses in ordinary text. +finds links and mail addresses in ordinary text. Prefer anonymous hyperlinks +(with a double underscore) over named hyperlinks (with a single underscore) +to avoid target name clashes. + Internal links ^^^^^^^^^^^^^^ @@ -343,7 +346,7 @@ they are used in the Python documentation. This is just an overview of Sphinx' extended markup capabilities; full coverage can be found in `its own documentation - `_. + `__. Meta-information markup diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 68350c4017..d90a14ce90 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -73,7 +73,7 @@ boolean abbreviated name with appropriate markup (for example, ``:type:`bool```). C API - Python's `API `_ used by C programmers + Python's `API `__ used by C programmers to write extension modules. All caps and unhyphenated. CPU @@ -122,7 +122,7 @@ such as "for example" or "that is." Diátaxis ======== -Python's documentation strives to follow the `Diátaxis `_ +Python's documentation strives to follow the `Diátaxis `__ framework. This means adapting the writing style according to the nature of the documentation that is being written. The framework splits documentation into four distinct types: tutorials, how-to guides, reference, and @@ -135,7 +135,7 @@ explanation. and abstract concepts should be avoided. Please consult the Diátaxis guide on :ref:`diataxis:tutorials` for more detail. -* `Python how-to guides `_ are +* `Python how-to guides `__ are designed to guide a user through a problem-field. Both tutorials and how-to guides are instructional rather than explanatory and should provide logical steps on how to complete a task. However, @@ -158,7 +158,7 @@ explanation. found throughout Python's documentation, for example the :ref:`python:unicode-howto`. -Please consult the `Diátaxis `_ guide for more +Please consult the `Diátaxis `__ guide for more detail. diff --git a/documentation/translations/coordinating.rst b/documentation/translations/coordinating.rst index 066237e5d9..a7872b6aec 100644 --- a/documentation/translations/coordinating.rst +++ b/documentation/translations/coordinating.rst @@ -12,7 +12,7 @@ Communication/help channels =========================== Discussions about translations occur on the Python Docs Discord -`#translations channel `_ and the +`#translations channel `__ and the `translations category `_ of the Python Discourse. For administrative issues, ping ``@python/editorial-board``. @@ -72,16 +72,16 @@ account, with the correct Git hierarchy and folder structure. This can be done in several ways, and depends on what translation process you plan to use. Each translation is assigned an appropriate lowercase -`IETF language tag `_. +`IETF language tag `__. The tag may have an optional subtag, joined with a dash. For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). The repository name is then: ``python-docs-TAG`` The name of each branch should be the Python version it holds translations for, for example, ``3.14``. The files should be structured like the source files -in `CPython/Doc `_. +in `CPython/Doc `__. A correctly set up repository looks like this: -`python-docs-pl `_ +`python-docs-pl `__ Below, the recommended ways for starting your repository are described. You can choose another way if you like; it’s up to you. @@ -100,7 +100,7 @@ Translation platform ~~~~~~~~~~~~~~~~~~~~ You can also start your translation using -`Transifex `_. +`Transifex `__. This will allow you to translate via the web interface, and to use shared automatically updated source files. @@ -155,7 +155,7 @@ PEP 545 summary Here are the essential points of :PEP:`545`: - Each translation is assigned an appropriate lowercase - `IETF language tag `_. + `IETF language tag `__. The tag may have an optional region subtag, joined with a dash. For example, ``pt`` (Portuguese) or ``pt-br`` (Brazilian Portuguese). @@ -210,10 +210,10 @@ Testing should ideally be set up in your repository, and will help catch errors early and ensure translation quality. Testing generally consists of building, and linting with :pypi:`sphinx-lint`. -See `this documentation `_ +See `this documentation `__ for sample workflows with usage guides. -The `dashboard `_ +The `dashboard `__ also tests translations and uploads error logs. @@ -289,7 +289,7 @@ Is there a Weblate instance we can translate on? ------------------------------------------------ There is currently no Weblate instance for Python translations. -See this `Discourse thread `_ +See this `Discourse thread `__ for updates. diff --git a/documentation/translations/translating.rst b/documentation/translations/translating.rst index 6252add5af..2e4f6cf91c 100644 --- a/documentation/translations/translating.rst +++ b/documentation/translations/translating.rst @@ -32,7 +32,7 @@ For more details about translations and their progress, see - :github:`GitHub ` * - `French (fr) `__ - Julien Palard (:github-user:`JulienPalard`) - - `AFPy/python-docs-fr `_, + - `AFPy/python-docs-fr `__, :github:`mirror ` * - `Greek (el) `__ - | Lysandros Nikolaou (:github-user:`lysnikolaou`), @@ -122,7 +122,7 @@ If there is already a repository for your language team (there may be links to Telegrams/Discords in the ``README``), join and introduce yourself. Your fellow translators will be more than happy to help! General discussions about translations occur on the Python Docs Discord -`#translations channel `_ and the +`#translations channel `__ and the `translations category `_ of the Python Discourse. .. _translation-style-guide: @@ -215,7 +215,7 @@ Code examples Translate values in code examples, that is string literals, and comments. Don't translate keywords or names, including variable, function, class, argument, -and attribute names. An example of a translated codeblock from the `tutorial `_ +and attribute names. An example of a translated codeblock from the `tutorial `__ is provided below: .. code-block:: python @@ -259,7 +259,7 @@ through the following resources from the Transifex documentation: Within the organization, a project for translating the :github:`Python Docs Sphinx Theme ` can also be found. -For further information about Transifex see our `documentation `_. +For further information about Transifex see our `documentation `__. Resources @@ -270,10 +270,10 @@ Some useful resources: - :ref:`git-boot-camp`: Several translations accept contributions by pull requests. Most have their own guide for how to do this, but this can provide useful tips. -- `Translation issues & improvements `_ GitHub project: +- `Translation issues & improvements `__ GitHub project: This project contains issues and pull requests that aim to improve the Python documentation for translations. -- `Python Pootle archive `_: +- `Python Pootle archive `__: Pootle is no longer used for translation. Contains translations for old Python versions. @@ -322,7 +322,7 @@ How do I translate the Python Docs Sphinx Theme? The Sphinx theme for the Python documentation supports localization. You can translate either on -`Transifex `_ +`Transifex `__ (see :ref:`translating on Transifex ` for more information) or locally by following the steps outlined below. @@ -357,7 +357,7 @@ The coordination team for my language is inactive, what do I do? ---------------------------------------------------------------- If you would like to coordinate, open a pull request in the -`devguide `_ adding yourself to the table +`devguide `__ adding yourself to the table at the top of this page, and ping ``@python/editorial-board``. diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index 2ecaa62f0e..b845e00aa6 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -33,7 +33,7 @@ relevant to CPython's workflow. .. note:: Setting up Git aliases for common tasks can be useful to you. You can get more information about that in - `Git documentation `_ + `Git documentation `__ .. _fork-cpython: @@ -280,7 +280,7 @@ Compare to the ``main`` branch:: $ git diff main Exclude generated files from diff using an ``attr`` -`pathspec `_ (note the +`pathspec `__ (note the single quotes):: $ git diff main ':(attr:!generated)' @@ -289,7 +289,7 @@ Exclude generated files from diff by default:: $ git config diff.generated.binary true -The ``generated`` `attribute `_ is +The ``generated`` `attribute `__ is defined in :cpy-file:`.gitattributes`, found in the repository root. .. _push-changes: @@ -389,8 +389,8 @@ you run ``git merge upstream/main``. When it happens, you need to resolve conflict. See these articles about resolving conflicts: -- `About merge conflicts `_ -- `Resolving a merge conflict using the command line `_ +- `About merge conflicts `__ +- `Resolving a merge conflict using the command line `__ .. _git_from_patch: @@ -443,8 +443,8 @@ Scenario: - A contributor made a pull request to CPython. - Before merging it, you want to be able to test their changes locally. -If you've got `GitHub CLI `_ or -`hub `_ installed, you can do:: +If you've got `GitHub CLI `__ or +`hub `__ installed, you can do:: $ gh co # GitHub CLI $ hub pr checkout # hub @@ -523,7 +523,7 @@ The bad example contains bullet points that are a direct effect of the PR life cycle, while being irrelevant to the final change. .. note:: - `How to Write a Git Commit Message `_ + `How to Write a Git Commit Message `__ is a nice article describing how to write a good commit message. Finally, press the :guilabel:`Confirm squash and merge` button. @@ -557,7 +557,7 @@ after it has been accepted and merged into ``main``. It is usually indicated by the label ``needs backport to X.Y`` on the pull request itself. Use the utility script -`cherry_picker.py `_ +`cherry_picker.py `__ to backport the commit. The commit hash for backporting is the squashed commit that was merged to @@ -649,12 +649,12 @@ To edit an open pull request that targets ``main``: GitHub CLI ---------- -`GitHub CLI `_ is a command-line +`GitHub CLI `__ is a command-line interface that allows you to create, update, and check GitHub issues and pull requests. You can install GitHub CLI `by following these instructions -`_. After installing, +`__. After installing, you need to authenticate:: $ gh auth login @@ -740,6 +740,6 @@ Change into a directory to work from that branch. For example:: .. seealso:: - * `Git Reference Manual `_ + * `Git Reference Manual `__ * `"Experiment on your code freely with Git worktree" - `_ + `__ diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 46975b7f73..d1f7e26a52 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -183,7 +183,7 @@ resolved as follows: When running the final command, Git may open an editor for writing a commit message. It is usually okay to leave that as-is and close the editor. -See `the merge command's documentation `_ +See `the merge command's documentation `__ for a detailed technical explanation. @@ -283,7 +283,7 @@ The automated checklist runs through: * Has the documentation been updated? * Has the test suite been updated? * Has an entry under ``Misc/NEWS.d/next`` been added? - (using `blurb-it `_, + (using `blurb-it `__, or the :pypi:`blurb` tool) * Has ``Misc/ACKS`` been updated? * Has ``configure`` been regenerated, if necessary? @@ -329,7 +329,7 @@ instructions on how the commit message should look like when merging a pull request. .. note:: - `How to Write a Git Commit Message `_ + `How to Write a Git Commit Message `__ is a nice article that describes how to write a good commit message. @@ -417,7 +417,7 @@ This will get your changes up to GitHub. Now you want to `create a pull request from your fork -`_. +`__. If this is a pull request in response to a pre-existing issue on the `issue tracker`_, please make sure to reference the issue number using ``gh-NNNNN:`` prefix in the pull request title and ``#NNNNN`` in the description. @@ -452,7 +452,7 @@ existing patch. In this case, both parties should sign the :ref:`CLA `. When creating a pull request based on another person's patch, provide attribution to the original patch author by adding "Co-authored-by: Author Name ." to the pull request description and commit message. -See `the GitHub article `_ +See `the GitHub article `__ on how to properly add the co-author info. See also :ref:`Applying a Patch to Git `. diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index a6ba77959a..df208f28cf 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -20,9 +20,9 @@ compiled version of the CPython interpreter (CPython is the version of Python available from https://www.python.org/). It also gives an overview of the directory structure of the CPython source code. -Alternatively, if you have `Docker `_ installed you +Alternatively, if you have `Docker `__ installed you might want to use `our official images -`_. These +`__. These contain the latest releases of several Python versions, along with Git head, and are provided for development and testing purposes only. @@ -38,23 +38,23 @@ Install Git .. c_install_git_start -CPython is developed using `Git `_ for version control. The Git +CPython is developed using `Git `__ for version control. The Git command line program is named ``git``; this is also used to refer to Git itself. Git is easily available for all common operating systems. - **Install** As the CPython repo is hosted on GitHub, please refer to either the - `GitHub setup instructions `_ - or the `Git project instructions `_ for step-by-step + `GitHub setup instructions `__ + or the `Git project instructions `__ for step-by-step installation directions. You may also want to consider a graphical client - such as `TortoiseGit `_ or - `GitHub Desktop `_. + such as `TortoiseGit `__ or + `GitHub Desktop `__. - **Configure** Configure :ref:`your name and email ` and create - `an SSH key `_ + `an SSH key `__ as this will allow you to interact with GitHub without typing a username and password each time you execute a command, such as ``git pull``, ``git push``, or ``git fetch``. On Windows, you should also @@ -141,7 +141,7 @@ Install pre-commit as a Git hook -------------------------------- To make sure your code is linted correctly, we recommend setting up -`pre-commit `_ as a Git hook:: +`pre-commit `__ as a Git hook:: $ pre-commit install --allow-missing-config pre-commit installed at .git/hooks/pre-commit @@ -170,7 +170,7 @@ working only on pure Python code the pydebug build provides several useful checks that one should not skip. .. seealso:: The effects of various configure and build flags are documented in - the `Python configure docs `_. + the `Python configure docs `__. .. _unix-compiling: @@ -822,7 +822,7 @@ some of CPython's modules (for example, ``zlib``). Note that Debian 12 and Ubuntu 24.04 do not have the ``libmpdec-dev`` package. You can safely remove it from the install list above and the Python build will use a bundled version. But we recommend using the system - `libmpdec `_ library. + `libmpdec `__ library. Either build it from sources or install this package from https://deb.sury.org. @@ -889,7 +889,7 @@ some of CPython's modules (for example, ``zlib``). --with-dbmliborder=gdbm:ndbm (``--with-dbmliborder`` is a workaround for a Homebrew-specific change - to ``gdbm``; see `#89452 `_ + to ``gdbm``; see `#89452 `__ for details.) .. tab:: MacPorts @@ -928,7 +928,7 @@ some of CPython's modules (for example, ``zlib``). For more details on various options and considerations for building, refer to the `macOS README - `_. + `__. .. note:: While you need a C compiler to build CPython, you don't need any knowledge of the C language to contribute! Vast areas of CPython are @@ -981,7 +981,7 @@ If a change is made to Python which relies on some POSIX system-specific functionality (such as using a new system call), it is necessary to update the :cpy-file:`configure` script to test for availability of the functionality. Python's :file:`configure` script is generated from :cpy-file:`configure.ac` -using `GNU Autoconf `_. +using `GNU Autoconf `__. After editing :file:`configure.ac`, run ``make regen-configure`` to generate :file:`configure`, :cpy-file:`pyconfig.h.in`, and :cpy-file:`aclocal.m4`. @@ -1185,13 +1185,13 @@ What is GitHub Codespaces? If you'd like to start contributing to CPython without needing to set up a local developer environment, you can use -`GitHub Codespaces `_. +`GitHub Codespaces `__. Codespaces is a cloud-based development environment offered by GitHub that allows developers to write, build, test, and debug code directly within their web browser or in Visual Studio Code (VS Code). To help you get started, CPython contains a -`devcontainer folder `_ +`devcontainer folder `__ with a JSON configuration file that provides consistent and versioned codespace configurations for all users of the project. It also contains a Dockerfile that allows you to set up the same environment but locally in a Docker container if @@ -1204,7 +1204,7 @@ Create a CPython codespace Here are the basic steps needed to contribute a pull request using Codespaces. You first need to navigate to the -`CPython repo `_ hosted on GitHub. +`CPython repo `__ hosted on GitHub. Then you will need to: @@ -1229,7 +1229,7 @@ Then you will need to: 2. A screen should appear that lets you know your codespace is being set up. (Note: Since the CPython devcontainer is provided, codespaces will use the configuration it specifies.) -3. A `web version of VS Code `_ will open inside your web +3. A `web version of VS Code `__ will open inside your web browser, already linked up with your code and a terminal to the remote codespace where CPython and its documentation have already been built. 4. Use the terminal with the usual Git commands to create a new branch, commit diff --git a/index.rst b/index.rst index e19bb88263..0af90e295e 100644 --- a/index.rst +++ b/index.rst @@ -31,7 +31,7 @@ instructions please see the :ref:`setup guide `. 1. Install and set up :ref:`Git ` and other dependencies (see the :ref:`Git Setup ` page for detailed information). -2. Fork `the CPython repository `_ +2. Fork `the CPython repository `__ to your GitHub account and :ref:`get the source code ` using:: git clone https://github.com//cpython @@ -91,7 +91,7 @@ instructions please see the :ref:`setup guide `. git checkout -b fix-issue-12345 main If an issue does not already exist, please `create it - `_. Trivial issues (for example, typo fixes) do + `__. Trivial issues (for example, typo fixes) do not require any issue to be created. 6. Once you fixed the issue, run the tests, and the patchcheck: @@ -125,10 +125,10 @@ instructions please see the :ref:`setup guide `. gh-12345: Fix some bug in spam module 8. Add a News entry into the ``Misc/NEWS.d`` directory as individual file. The - news entry can be created by using `blurb-it `_, + news entry can be created by using `blurb-it `__, or the :pypi:`blurb` tool and its ``blurb add`` command. Please read more about ``blurb`` in its - `repository `_. + `repository `__. .. note:: @@ -159,12 +159,12 @@ this guide, then the `Core Python Mentorship`_ group is available to help guide contributors through the process. A number of individuals from the Python community have contributed to a series -of excellent guides at `Open Source Guides `_. +of excellent guides at `Open Source Guides `__. Core developers and contributors alike will find the following guides useful: -* `How to Contribute to Open Source `_ -* `Building Welcoming Communities `_ +* `How to Contribute to Open Source `__ +* `Building Welcoming Communities `__ Guide for contributing to Python: @@ -251,8 +251,8 @@ Key resources * `Buildbot status`_ * Source code - * `Browse online `_ - * `Snapshot of the *main* branch `_ + * `Browse online `__ + * `Snapshot of the *main* branch `__ * PEPs_ (Python Enhancement Proposals) * :ref:`help` @@ -279,7 +279,7 @@ Additional resources * :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 `_ + `wiki `__ * `python.org maintenance`_ * :ref:`Search this guide ` diff --git a/internals/compiler.rst b/internals/compiler.rst index 5b43e1e6dc..f22039c649 100644 --- a/internals/compiler.rst +++ b/internals/compiler.rst @@ -7,4 +7,4 @@ Compiler design .. highlight:: none This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst index acbcedf0e8..d86bbf8a18 100644 --- a/internals/garbage-collector.rst +++ b/internals/garbage-collector.rst @@ -9,4 +9,4 @@ Garbage collector design .. highlight:: none This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/internals/interpreter.rst b/internals/interpreter.rst index a7ae39c120..52c1509441 100644 --- a/internals/interpreter.rst +++ b/internals/interpreter.rst @@ -5,4 +5,4 @@ The bytecode interpreter ======================== This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/internals/parser.rst b/internals/parser.rst index 688ad61e77..9700c25b05 100644 --- a/internals/parser.rst +++ b/internals/parser.rst @@ -7,4 +7,4 @@ Guide to the parser .. highlight:: none This document is now part of the -`CPython Internals Docs `_. +`CPython Internals Docs `__. diff --git a/testing/buildbots.rst b/testing/buildbots.rst index e038499354..1e711ab6bb 100644 --- a/testing/buildbots.rst +++ b/testing/buildbots.rst @@ -11,7 +11,7 @@ branches `, 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 several *builders*, one per active branch: when a new change is pushed -to this branch on the public `GitHub repository `_, all corresponding builders +to this branch on the public `GitHub repository `__, all corresponding builders will schedule a new build to be run as soon as possible. The build steps run by the buildbots are the following: diff --git a/testing/coverage.rst b/testing/coverage.rst index d01141a7dc..c34bb5235a 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -127,7 +127,7 @@ to install coverage. You can now use python without the ./ for the rest of these instructions, as long as your venv is activated. For more info on venv see `Virtual Environment -`_ documentation. +`__ documentation. If this does not work for you for some reason, you should try using the in-development version of coverage.py to see if it has been updated as needed. diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index cac7bb63d5..a0fbf9681a 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -20,12 +20,12 @@ to go about setting up a buildbot worker, getting it added, and some hints about buildbot maintenance. Anyone running a buildbot that is part of the fleet should subscribe to the -`python-buildbots `_ +`python-buildbots `__ mailing list. This mailing list is also the place to contact if you want to contribute a buildbot but have questions. As for what kind of buildbot to run...take a look at our `current fleet -`_. Pretty much anything that isn't +`__. Pretty much anything that isn't on that list would be interesting: different Linux/Unix distributions, different versions of the various OSes, other OSes if you or someone are prepared to make the test suite actually pass on that new OS. Even if you only @@ -47,7 +47,7 @@ compiled python. In order to set up the buildbot software, you will need to obtain an identifier and password for your worker so it can join the fleet. Open an issue in the -`configuration repository `_ +`configuration repository `__ to discuss adding your worker and to obtain the needed workername and password. You can do some of the steps that follow before having the credentials, but it is easiest to have them before @@ -60,7 +60,7 @@ Setting up the buildbot worker Conventional always-on machines ------------------------------- -You need a recent version of the `buildbot `_ software, +You need a recent version of the `buildbot `__ software, and you will probably want a separate 'buildbot' user to run the buildbot software. You may also want to set the buildbot up using a virtual environment, depending on how you manage your system. We won't cover how to that @@ -103,7 +103,7 @@ can put the ``buildarea`` wherever you want to):: :file:`Scripts` directory of your Python installation.) On Windows, `the maximum length for a path is limited -`_. +`__. This might cause some tests to fail, unless long paths support is enabled. Use this PowerShell command to check whether long paths are enabled:: @@ -254,7 +254,7 @@ For Windows: * Alternatively (note: don't do both!), set up the worker service as described in the `buildbot documentation - `_. + `__. To start the worker running for your initial testing, you can do:: @@ -262,7 +262,7 @@ To start the worker running for your initial testing, you can do:: Then you can either wait for someone to make a commit, or you can pick a builder associated with your worker from the `list of builders -`_ and force a build. +`__ and force a build. In any case you should initially monitor builds on your builders to make sure the tests are passing and to resolve any platform issues that may be revealed @@ -273,7 +273,7 @@ idea. .. note:: If your buildbot worker is disconnecting regularly, it may be a symptom of the default ``keepalive`` value (``600`` for 10 minutes) being `set - `_ + `__ too high. You can change it to a lower value (for example, ``180`` for 3 minutes) in the ``buildbot.tac`` file found in your build area. @@ -282,7 +282,7 @@ Latent workers -------------- We also support running `latent workers -`_ +`__ on the AWS EC2 service. To set up such a worker: * Start an instance of your chosen base AMI and set it up as a @@ -305,7 +305,7 @@ instance(s), so it is recommended to periodically check and make sure there are no "zombie" instances running on your account, created by the buildbot master. Also, if you notice that your worker seems to have been down for an unexpectedly long time, please ping the `python-buildbots -`_ list to +`__ list to request that the master be restarted. Latent workers should also be updated periodically to include operating system @@ -390,7 +390,7 @@ Required resources ================== Based on the last time we did a `survey -`_ on +`__ on buildbot requirements, the recommended resource allocations for a python buildbot are at least: @@ -408,7 +408,7 @@ Security considerations ======================= We only allow builds to be triggered against commits to the -`CPython repository on GitHub `_. +`CPython repository on GitHub `__. This means that the code your buildbot will run will have been vetted by a committer. However, mistakes and bugs happen, as could a compromise, so keep this in mind when siting your buildbot on your network and establishing the security around it. @@ -427,7 +427,7 @@ VM setup. But if you are confident in your setup, we'd love to have a buildbot that runs python as root. Note that the above is a summary of a `discussion -`_ on +`__ on python-dev about buildbot security that includes examples of the tests for which privilege matters. There was no final consensus, but the information is useful as a point of reference. diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 83a4a28610..34101bd2d2 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -286,7 +286,7 @@ Benchmarks Benchmarking is useful to test that a change does not degrade performance. -`The Python Benchmark Suite `_ +`The Python Benchmark Suite `__ has a collection of benchmarks for all Python implementations. Documentation about running the benchmarks is in the `README.txt -`_ of the repo. +`__ of the repo. diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index 8c21a17fea..f4f8b16dd4 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -16,7 +16,7 @@ How to format my comments nicely? ================================= There is a wonderful `beginner guide to writing and formatting on GitHub -`_. +`__. Highly recommended. One pro-tip we can sell you right here is that if you want to paste @@ -43,7 +43,7 @@ Use Markdown links. If you link to the default GitHub path, the file will link to the latest current version on the given branch. You can get a permanent link to a given revision of a given file by -`pressing "y" `_. +`pressing "y" `__. How to do advanced searches? ============================ @@ -80,7 +80,7 @@ Add a checkbox list like this in the issue description:: then those will become sub-tasks on the given issue. Moreover, GitHub will automatically mark a task as complete if the other referenced issue is closed. More details in the `official GitHub documentation -`_. +`__. What on earth is a "mannequin"? =============================== @@ -88,7 +88,7 @@ What on earth is a "mannequin"? For issues migrated to GitHub from `bpo`_ where the authors or commenters are not core developers, we opted not to link to their GitHub accounts directly. Users not in the `python organization on GitHub -`_ might not like comments to +`__ might not like comments to appear under their name from an automated import. Others never linked GitHub on `bpo`_ in the first place so linking their account, if any, would be impossible. diff --git a/triage/labels.rst b/triage/labels.rst index 34c7dc26c9..96e0d8f58e 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -9,7 +9,7 @@ Triagers, core developers and bots can add labels on GitHub to categorize issues and pull requests. Many labels are shared for both use cases, while some are dedicated only to one. Below is a possibly inexhaustive list, but it should get -you going. For a full list, see `here `_. +you going. For a full list, see `here `__. .. _general-purpose-labels: @@ -73,7 +73,7 @@ we don't have a dedicated Unix label. Use the :gh-label:`OS-unsupported` label for issues on platforms outside the support tiers defined in :pep:`11`. Applying this label adds the issue to -`a GitHub project `_ where +`a GitHub project `__ where it can be categorized further. See also the :ref:`Platform experts list `. @@ -92,7 +92,7 @@ they are encouraged to subscribe to them. Depending on the label, this might also automatically add the issue to a GitHub project. You can see the `full list of topic labels on GitHub -`_. +`__. .. _Version labels: diff --git a/triage/triage-team.rst b/triage/triage-team.rst index 68a88457e4..7acebc130c 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -86,14 +86,14 @@ Any existing active contributor to the Python repository on GitHub can transition into becoming a Python triager. They can request this to any core developer, either confidentially via a DM in Discourse, or publicly by opening an `issue in the core-workflow repository -`_. +`__. If the core developer decides you are ready to gain the extra privileges on the tracker, they will ask a :ref:`Python organization admin ` to invite you to the Python organisation, and then act as a mentor to you until you are ready to do things entirely on your own. For every new triager, it would be great to announce them in the -`Committers category `_ -on the `Python Discourse `_ +`Committers category `__ +on the `Python Discourse `__ (`example announcement `__). diff --git a/versions.rst b/versions.rst index 0a52829c2f..d0f8379915 100644 --- a/versions.rst +++ b/versions.rst @@ -7,14 +7,14 @@ Status of Python versions The ``main`` branch is currently the future Python |main_version|, and is the only branch that accepts new features. The latest release for each Python -version can be found on the `download page `_. +version can be found on the `download page `__. .. raw:: html :file: include/release-cycle.svg (See :ref:`below ` for a chart with older versions. -Another useful visualization is `endoflife.date/python `_.) +Another useful visualization is `endoflife.date/python `__.) Supported versions