diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 8b3ee2b3cc..1b701a6b6d 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -186,7 +186,7 @@ clone. .. _committing-active-branches: Seeing active branches -'''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^ If you use ``git branch``, then you will see a :ref:`list of branches `. The only branch that receives new features is @@ -198,7 +198,7 @@ originate on ``main`` and then be ported back to older branches. .. _branch-merge: Backporting changes to an older version -''''''''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If it is determined that a pull request needs to be backported into one or more of the maintenance branches, then a core developer can apply the label @@ -236,7 +236,7 @@ can apply labels to GitHub pull requests). Reverting a merged pull request -''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To revert a merged pull request, press the ``Revert`` button at the bottom of the pull request. That will bring up the page to create a diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 66b88e784d..12e14889e9 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -138,7 +138,7 @@ Notifications ------------- Following categories (category notifications) -''''''''''''''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Notifications can be set for individual categories and topics. To change any of these defaults, you can either go to your user preferences, or visit the category @@ -151,7 +151,7 @@ All categories are set by default in Normal mode where you will only be notified if someone mentions your @name or replies to you. Following individual threads (topic notifications) -'''''''''''''''''''''''''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To follow any individual topics or threads, you can adjust your notifications through the notification button 🔔 found on the right of the topic at the end @@ -160,7 +160,7 @@ Select "Watching" and you will be notified when there is any new updated reply from that particular thread. 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 `_. diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 613af736ba..704098cdd1 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -34,7 +34,7 @@ and *null* for final releases), and ``N`` is the release serial number. Some examples of release tags: ``v3.7.0a1``, ``v3.6.3``, ``v2.7.14rc1``. Branches -'''''''' +-------- There is a branch for each *feature version*, whether released or not (e.g. 3.7, 3.8). @@ -43,7 +43,7 @@ There is a branch for each *feature version*, whether released or not (e.g. .. _indevbranch: In-development (main) branch ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``main`` branch is the branch for the next feature release; it is under active development for all kinds of changes: new features, semantic @@ -65,7 +65,7 @@ for release 3.n. .. _maintbranch: Maintenance branches --------------------- +^^^^^^^^^^^^^^^^^^^^ A branch for a previous feature release, currently being maintained for bug fixes, or for the next feature release in its @@ -104,7 +104,7 @@ which followed the release of 3.5.1. .. _secbranch: Security branches ------------------ +^^^^^^^^^^^^^^^^^ A branch less than 5 years old but no longer in bugfix mode is a security branch. @@ -126,7 +126,7 @@ security patches have been applied to the branch. These releases have a .. _eolbranch: End-of-life branches --------------------- +^^^^^^^^^^^^^^^^^^^^ The code base for a release cycle which has reached end-of-life status is frozen and no longer has a branch in the repo. The final state of @@ -141,7 +141,7 @@ The latest release for each Python version can be found on the `download page .. _stages: Stages -'''''' +------ Based on what stage the :ref:`in-development ` version of Python is in, the responsibilities of a core developer change in regards to commits @@ -149,7 +149,7 @@ to the :abbr:`VCS (version control system)`. Pre-alpha ---------- +^^^^^^^^^ The branch is in this stage when no official release has been done since the latest final release. There are no special restrictions placed on @@ -159,7 +159,7 @@ breaking the buildbots). .. _alpha: Alpha ------ +^^^^^ Alpha releases typically serve as a reminder to core developers that they need to start getting in changes that change semantics or add something to @@ -169,7 +169,7 @@ restrictions are in place while in alpha. .. _beta: Beta ----- +^^^^ After a first beta release is published, no new features are accepted. Only bug fixes and improvements to documentation and tests can now be committed. @@ -187,7 +187,7 @@ new information about the creation of the 3.5 maintenance branch during beta. .. _rc: Release Candidate (RC) ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ A branch preparing for an RC release can only have bugfixes applied that have been reviewed by other core developers. Generally, these issues must be @@ -206,7 +206,7 @@ a core developer. .. _final: Final ------ +^^^^^ When a final release is being cut, only the release manager (RM) can make changes to the branch. After the final release is published, the full @@ -214,13 +214,13 @@ changes to the branch. After the final release is published, the full Repository administration -''''''''''''''''''''''''' +------------------------- The source code is currently hosted on `GitHub `_ in the `Python organization `_. Organization repository policy ------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Within the `GitHub Python organization `_, repositories are expected to relate to the Python language, the CPython @@ -261,7 +261,7 @@ specifically want to “bless” one implementation (as with e.g. Organization owner policy -------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^ The GitHub Organization Owner role allows for full management of all aspects of the Python organization. Allowing for visibility and management of all aspects @@ -288,7 +288,7 @@ Owner of the Python Organization. .. _current owners: Current owners --------------- +^^^^^^^^^^^^^^ +----------------------+--------------------------------+-----------------+ | Name | Role | GitHub Username | @@ -314,7 +314,7 @@ mentioned to request assistance from an organization owner. .. _be performed: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permissions-for-organization-roles Repository administrator role policy ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Administrator role on the repository allows for managing all aspects including collaborators, access control, integrations, webhooks, and branch @@ -335,7 +335,7 @@ Multi-Factor Authentication must be enabled by the user in order to remain an Administrator of the repository. Current administrators ----------------------- +^^^^^^^^^^^^^^^^^^^^^^ +-------------------+----------------------------------------------------------+-----------------+ | Name | Role | GitHub Username | @@ -360,7 +360,7 @@ Current administrators +-------------------+----------------------------------------------------------+-----------------+ Repository release manager role policy --------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Release Managers for :ref:`in-development `, :ref:`maintenance `, and :ref:`security mode ` Python releases are diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index 9ead7d7069..c9e1ab429b 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -62,7 +62,8 @@ are not taken lightly. Acceptable types of modules -''''''''''''''''''''''''''' +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Typically two types of modules get added to the stdlib. One type is a module which implements something that is difficult to get right. A good example of this is the :py:mod:`multiprocessing` package. Working out the various OS @@ -83,7 +84,8 @@ it. Requirements -'''''''''''' +^^^^^^^^^^^^ + In order for a module to even be considered for inclusion into the stdlib, a couple of requirements must be met. @@ -121,7 +123,7 @@ uniform. Proposal process -'''''''''''''''' +^^^^^^^^^^^^^^^^ If the module you want to propose adding to the stdlib meets the requirements, you may propose its inclusion diff --git a/documentation/markup.rst b/documentation/markup.rst index 0f31e345db..7e237462ca 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -165,14 +165,14 @@ Hyperlinks ---------- External links -'''''''''''''' +^^^^^^^^^^^^^^ 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. Internal links -'''''''''''''' +^^^^^^^^^^^^^^ Internal linking is done via a special reST role, see the section on specific markup, :ref:`doc-ref-role`. diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 8dffcd5cde..b2dc2f1c25 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -227,7 +227,7 @@ the interpreter you just built. Clang -''''' +^^^^^ If you are using clang_ to build CPython, some flags you might want to set to quiet some standard warnings which are specifically superfluous to CPython are @@ -246,7 +246,7 @@ still build properly). Optimization -'''''''''''' +^^^^^^^^^^^^ If you are trying to improve CPython's performance, you will probably want to use an optimized build of CPython. It can take a lot longer to build CPython diff --git a/internals/parser.rst b/internals/parser.rst index 2b9a8df035..db9922a80d 100644 --- a/internals/parser.rst +++ b/internals/parser.rst @@ -161,12 +161,12 @@ Grammar expressions ------------------- ``# comment`` -''''''''''''' +^^^^^^^^^^^^^ Python-style comments. ``e1 e2`` -''''''''' +^^^^^^^^^ Match ``e1``, then match ``e2``. @@ -175,7 +175,7 @@ Match ``e1``, then match ``e2``. rule_name: first_rule second_rule ``e1 | e2`` -''''''''''' +^^^^^^^^^^^ Match ``e1`` or ``e2``. @@ -190,7 +190,7 @@ first alternative, like so: | second_alt ``( e )`` -''''''''' +^^^^^^^^^ Match ``e``. @@ -206,7 +206,7 @@ operator together with the repeat operators: rule_name: (e1 e2)* ``[ e ] or e?`` -''''''''''''''' +^^^^^^^^^^^^^^^ Optionally match ``e``. @@ -222,7 +222,7 @@ optional: rule_name: e (',' e)* [','] ``e*`` -'''''' +^^^^^^ Match zero or more occurrences of ``e``. @@ -231,7 +231,7 @@ Match zero or more occurrences of ``e``. rule_name: (e1 e2)* ``e+`` -'''''' +^^^^^^ Match one or more occurrences of ``e``. @@ -240,7 +240,7 @@ Match one or more occurrences of ``e``. rule_name: (e1 e2)+ ``s.e+`` -'''''''' +^^^^^^^^ Match one or more occurrences of ``e``, separated by ``s``. The generated parse tree does not include the separator. This is otherwise identical to @@ -251,14 +251,14 @@ tree does not include the separator. This is otherwise identical to rule_name: ','.e+ ``&e`` -'''''' +^^^^^^ .. _peg-positive-lookahead: Succeed if ``e`` can be parsed, without consuming any input. ``!e`` -'''''' +^^^^^^ .. _peg-negative-lookahead: @@ -273,7 +273,7 @@ consists of an atom, which is not followed by a ``.`` or a ``(`` or a primary: atom !'.' !'(' !'[' ``~`` -'''''' +^^^^^ Commit to the current alternative, even if it fails to parse (this is called the "cut"). diff --git a/testing/coverage.rst b/testing/coverage.rst index f0da943494..62f0751481 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -88,7 +88,7 @@ provided by the stdlib then you can :ref:`use test.regrtest .. _install_coverage: Install coverage -'''''''''''''''' +^^^^^^^^^^^^^^^^ By default, pip will not install into the in-development version of Python you just built, and this built version of Python will not see packages installed @@ -143,7 +143,7 @@ it. For this, you will again need to use the full path to that installation. .. _coverage_usage: Basic usage -''''''''''' +^^^^^^^^^^^ The following command will tell you if your copy of coverage works (substitute ``COVERAGEDIR`` with the directory where your clone exists, e.g. @@ -197,7 +197,7 @@ with pages that visibly show what lines of code were or were not executed. .. _branch_coverage: Branch coverage -''''''''''''''' +^^^^^^^^^^^^^^^ For the truly daring, you can use another powerful feature of coverage.py: branch coverage. Testing every possible branch path through code, while a great