From 28400485063850b548ff2345e5c713c8b1754e4a Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Tue, 14 Jun 2022 11:12:26 +0100 Subject: [PATCH 01/21] Reorganise to subdirectories --- clang.rst => advanced-tools/clang.rst | 0 coverity.rst => advanced-tools/coverity.rst | 0 gdb.rst => advanced-tools/gdb.rst | 0 coredev.rst => core-developers/become-core-developer.rst | 0 committing.rst => core-developers/committing.rst | 0 developers.rst => core-developers/developer-log.rst | 0 developers.csv => core-developers/developers.csv | 0 experts.rst => core-developers/experts.rst | 0 motivations.rst => core-developers/motivations.rst | 0 c-api.rst => developer-workflow/c-api.rst | 0 .../communication-channels.rst | 0 devcycle.rst => developer-workflow/development-cycle.rst | 0 extensions.rst => developer-workflow/extension-modules.rst | 0 grammar.rst => developer-workflow/grammar.rst | 0 langchanges.rst => developer-workflow/lang-changes.rst | 0 porting.rst => developer-workflow/porting.rst | 0 stdlibchanges.rst => developer-workflow/stdlib.rst | 0 docquality.rst => documentation/help-documenting.rst | 0 documenting.rst => documentation/start-documenting.rst | 0 fixingissues.rst => getting-started/fixing-issues.rst | 0 help.rst => getting-started/getting-help.rst | 0 gitbootcamp.rst => getting-started/git-boot-camp.rst | 0 pullrequest.rst => getting-started/pull-request-lifecycle.rst | 0 setup.rst => getting-started/setup-building.rst | 0 compiler.rst => internals/compiler.rst | 0 exploring.rst => internals/exploring.rst | 0 garbage_collector.rst => internals/garbage-collector.rst | 0 parser.rst => internals/parser.rst | 0 buildbots.rst => testing/buildbots.rst | 0 coverage.rst => testing/coverage.rst | 0 buildworker.rst => testing/new-buildbot-worker.rst | 0 runtests.rst => testing/run-write-tests.rst | 0 silencewarnings.rst => testing/silence-warnings.rst | 0 gh-faq.rst => triage/github-bpo-faq.rst | 0 tracker.rst => triage/issue-tracker.rst | 0 gh-labels.rst => triage/labels.rst | 0 triaging.rst => triage/triaging.rst | 0 37 files changed, 0 insertions(+), 0 deletions(-) rename clang.rst => advanced-tools/clang.rst (100%) rename coverity.rst => advanced-tools/coverity.rst (100%) rename gdb.rst => advanced-tools/gdb.rst (100%) rename coredev.rst => core-developers/become-core-developer.rst (100%) rename committing.rst => core-developers/committing.rst (100%) rename developers.rst => core-developers/developer-log.rst (100%) rename developers.csv => core-developers/developers.csv (100%) rename experts.rst => core-developers/experts.rst (100%) rename motivations.rst => core-developers/motivations.rst (100%) rename c-api.rst => developer-workflow/c-api.rst (100%) rename communication.rst => developer-workflow/communication-channels.rst (100%) rename devcycle.rst => developer-workflow/development-cycle.rst (100%) rename extensions.rst => developer-workflow/extension-modules.rst (100%) rename grammar.rst => developer-workflow/grammar.rst (100%) rename langchanges.rst => developer-workflow/lang-changes.rst (100%) rename porting.rst => developer-workflow/porting.rst (100%) rename stdlibchanges.rst => developer-workflow/stdlib.rst (100%) rename docquality.rst => documentation/help-documenting.rst (100%) rename documenting.rst => documentation/start-documenting.rst (100%) rename fixingissues.rst => getting-started/fixing-issues.rst (100%) rename help.rst => getting-started/getting-help.rst (100%) rename gitbootcamp.rst => getting-started/git-boot-camp.rst (100%) rename pullrequest.rst => getting-started/pull-request-lifecycle.rst (100%) rename setup.rst => getting-started/setup-building.rst (100%) rename compiler.rst => internals/compiler.rst (100%) rename exploring.rst => internals/exploring.rst (100%) rename garbage_collector.rst => internals/garbage-collector.rst (100%) rename parser.rst => internals/parser.rst (100%) rename buildbots.rst => testing/buildbots.rst (100%) rename coverage.rst => testing/coverage.rst (100%) rename buildworker.rst => testing/new-buildbot-worker.rst (100%) rename runtests.rst => testing/run-write-tests.rst (100%) rename silencewarnings.rst => testing/silence-warnings.rst (100%) rename gh-faq.rst => triage/github-bpo-faq.rst (100%) rename tracker.rst => triage/issue-tracker.rst (100%) rename gh-labels.rst => triage/labels.rst (100%) rename triaging.rst => triage/triaging.rst (100%) diff --git a/clang.rst b/advanced-tools/clang.rst similarity index 100% rename from clang.rst rename to advanced-tools/clang.rst diff --git a/coverity.rst b/advanced-tools/coverity.rst similarity index 100% rename from coverity.rst rename to advanced-tools/coverity.rst diff --git a/gdb.rst b/advanced-tools/gdb.rst similarity index 100% rename from gdb.rst rename to advanced-tools/gdb.rst diff --git a/coredev.rst b/core-developers/become-core-developer.rst similarity index 100% rename from coredev.rst rename to core-developers/become-core-developer.rst diff --git a/committing.rst b/core-developers/committing.rst similarity index 100% rename from committing.rst rename to core-developers/committing.rst diff --git a/developers.rst b/core-developers/developer-log.rst similarity index 100% rename from developers.rst rename to core-developers/developer-log.rst diff --git a/developers.csv b/core-developers/developers.csv similarity index 100% rename from developers.csv rename to core-developers/developers.csv diff --git a/experts.rst b/core-developers/experts.rst similarity index 100% rename from experts.rst rename to core-developers/experts.rst diff --git a/motivations.rst b/core-developers/motivations.rst similarity index 100% rename from motivations.rst rename to core-developers/motivations.rst diff --git a/c-api.rst b/developer-workflow/c-api.rst similarity index 100% rename from c-api.rst rename to developer-workflow/c-api.rst diff --git a/communication.rst b/developer-workflow/communication-channels.rst similarity index 100% rename from communication.rst rename to developer-workflow/communication-channels.rst diff --git a/devcycle.rst b/developer-workflow/development-cycle.rst similarity index 100% rename from devcycle.rst rename to developer-workflow/development-cycle.rst diff --git a/extensions.rst b/developer-workflow/extension-modules.rst similarity index 100% rename from extensions.rst rename to developer-workflow/extension-modules.rst diff --git a/grammar.rst b/developer-workflow/grammar.rst similarity index 100% rename from grammar.rst rename to developer-workflow/grammar.rst diff --git a/langchanges.rst b/developer-workflow/lang-changes.rst similarity index 100% rename from langchanges.rst rename to developer-workflow/lang-changes.rst diff --git a/porting.rst b/developer-workflow/porting.rst similarity index 100% rename from porting.rst rename to developer-workflow/porting.rst diff --git a/stdlibchanges.rst b/developer-workflow/stdlib.rst similarity index 100% rename from stdlibchanges.rst rename to developer-workflow/stdlib.rst diff --git a/docquality.rst b/documentation/help-documenting.rst similarity index 100% rename from docquality.rst rename to documentation/help-documenting.rst diff --git a/documenting.rst b/documentation/start-documenting.rst similarity index 100% rename from documenting.rst rename to documentation/start-documenting.rst diff --git a/fixingissues.rst b/getting-started/fixing-issues.rst similarity index 100% rename from fixingissues.rst rename to getting-started/fixing-issues.rst diff --git a/help.rst b/getting-started/getting-help.rst similarity index 100% rename from help.rst rename to getting-started/getting-help.rst diff --git a/gitbootcamp.rst b/getting-started/git-boot-camp.rst similarity index 100% rename from gitbootcamp.rst rename to getting-started/git-boot-camp.rst diff --git a/pullrequest.rst b/getting-started/pull-request-lifecycle.rst similarity index 100% rename from pullrequest.rst rename to getting-started/pull-request-lifecycle.rst diff --git a/setup.rst b/getting-started/setup-building.rst similarity index 100% rename from setup.rst rename to getting-started/setup-building.rst diff --git a/compiler.rst b/internals/compiler.rst similarity index 100% rename from compiler.rst rename to internals/compiler.rst diff --git a/exploring.rst b/internals/exploring.rst similarity index 100% rename from exploring.rst rename to internals/exploring.rst diff --git a/garbage_collector.rst b/internals/garbage-collector.rst similarity index 100% rename from garbage_collector.rst rename to internals/garbage-collector.rst diff --git a/parser.rst b/internals/parser.rst similarity index 100% rename from parser.rst rename to internals/parser.rst diff --git a/buildbots.rst b/testing/buildbots.rst similarity index 100% rename from buildbots.rst rename to testing/buildbots.rst diff --git a/coverage.rst b/testing/coverage.rst similarity index 100% rename from coverage.rst rename to testing/coverage.rst diff --git a/buildworker.rst b/testing/new-buildbot-worker.rst similarity index 100% rename from buildworker.rst rename to testing/new-buildbot-worker.rst diff --git a/runtests.rst b/testing/run-write-tests.rst similarity index 100% rename from runtests.rst rename to testing/run-write-tests.rst diff --git a/silencewarnings.rst b/testing/silence-warnings.rst similarity index 100% rename from silencewarnings.rst rename to testing/silence-warnings.rst diff --git a/gh-faq.rst b/triage/github-bpo-faq.rst similarity index 100% rename from gh-faq.rst rename to triage/github-bpo-faq.rst diff --git a/tracker.rst b/triage/issue-tracker.rst similarity index 100% rename from tracker.rst rename to triage/issue-tracker.rst diff --git a/gh-labels.rst b/triage/labels.rst similarity index 100% rename from gh-labels.rst rename to triage/labels.rst diff --git a/triaging.rst b/triage/triaging.rst similarity index 100% rename from triaging.rst rename to triage/triaging.rst From 4ca48b1808987625c5819ba6e8c217314ed5aebd Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 19:29:24 +0100 Subject: [PATCH 02/21] Add index files --- advanced-tools/index.rst | 10 ++++++++++ core-developers/index.rst | 12 ++++++++++++ developer-workflow/index.rst | 15 +++++++++++++++ documentation/index.rst | 9 +++++++++ getting-started/index.rst | 12 ++++++++++++ internals/index.rst | 11 +++++++++++ testing/index.rst | 12 ++++++++++++ triage/index.rst | 11 +++++++++++ 8 files changed, 92 insertions(+) create mode 100644 advanced-tools/index.rst create mode 100644 core-developers/index.rst create mode 100644 developer-workflow/index.rst create mode 100644 documentation/index.rst create mode 100644 getting-started/index.rst create mode 100644 internals/index.rst create mode 100644 testing/index.rst create mode 100644 triage/index.rst diff --git a/advanced-tools/index.rst b/advanced-tools/index.rst new file mode 100644 index 0000000000..afa96741f3 --- /dev/null +++ b/advanced-tools/index.rst @@ -0,0 +1,10 @@ +============== +Advanced Tools +============== + +.. toctree:: + :maxdepth: 5 + + gdb + clang + coverity diff --git a/core-developers/index.rst b/core-developers/index.rst new file mode 100644 index 0000000000..3a037151fb --- /dev/null +++ b/core-developers/index.rst @@ -0,0 +1,12 @@ +=============== +Core Developers +=============== + +.. toctree:: + :maxdepth: 5 + + committing + experts + developer-log + motivations + become-core-developer diff --git a/developer-workflow/index.rst b/developer-workflow/index.rst new file mode 100644 index 0000000000..bc90a832af --- /dev/null +++ b/developer-workflow/index.rst @@ -0,0 +1,15 @@ +==================== +Development Workflow +==================== + +.. toctree:: + :maxdepth: 5 + + communication-channels + development-cycle + stdlib + extension-modules + c-api + lang-changes + grammar + porting diff --git a/documentation/index.rst b/documentation/index.rst new file mode 100644 index 0000000000..8213b0ceda --- /dev/null +++ b/documentation/index.rst @@ -0,0 +1,9 @@ +============= +Documentation +============= + +.. toctree:: + :maxdepth: 5 + + start-documenting + help-documenting diff --git a/getting-started/index.rst b/getting-started/index.rst new file mode 100644 index 0000000000..420f1231c9 --- /dev/null +++ b/getting-started/index.rst @@ -0,0 +1,12 @@ +=============== +Getting Started +=============== + +.. toctree:: + :maxdepth: 5 + + setup-building + fixing-issues + git-boot-camp + pull-request-lifecycle + getting-help diff --git a/internals/index.rst b/internals/index.rst new file mode 100644 index 0000000000..ce04c665c1 --- /dev/null +++ b/internals/index.rst @@ -0,0 +1,11 @@ +=================== +CPython's Internals +=================== + +.. toctree:: + :maxdepth: 5 + + exploring + parser + compiler + garbage-collector diff --git a/testing/index.rst b/testing/index.rst new file mode 100644 index 0000000000..4a7247c985 --- /dev/null +++ b/testing/index.rst @@ -0,0 +1,12 @@ +===================== +Testing and Buildbots +===================== + +.. toctree:: + :maxdepth: 5 + + run-write-tests + silence-warnings + coverage + buildbots + new-buildbot-worker diff --git a/triage/index.rst b/triage/index.rst new file mode 100644 index 0000000000..f948cf36bd --- /dev/null +++ b/triage/index.rst @@ -0,0 +1,11 @@ +=================== +Issues and Triaging +=================== + +.. toctree:: + :maxdepth: 5 + + issue-tracker + triaging + labels + github-bpo-faq From 7ad5984ea055c905b3eeb3c0217f1baac747a014 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 19:34:01 +0100 Subject: [PATCH 03/21] Update master toctree --- index.rst | 42 ++++++++---------------------------------- 1 file changed, 8 insertions(+), 34 deletions(-) diff --git a/index.rst b/index.rst index 0ffb6477ab..2bf704128f 100644 --- a/index.rst +++ b/index.rst @@ -297,40 +297,14 @@ Full Table of Contents .. toctree:: :maxdepth: 3 - setup - help - pullrequest - runtests - coverage - docquality - documenting - silencewarnings - fixingissues - tracker - triaging - communication - porting - coredev - developers - committing - devcycle - buildbots - stdlibchanges - langchanges - experts - gdb - exploring - grammar - parser - compiler - garbage_collector - extensions - c-api - coverity - clang - buildworker - motivations - gitbootcamp + getting-started/index + developer-workflow/index + triage/index + documentation/index + testing/index + core-developers/index + internals/index + advanced-tools/index appendix .. _Buildbot status: https://www.python.org/dev/buildbot/ From fbe15cc96fc19264970fde5567c593c56ce3bc10 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 19:37:15 +0100 Subject: [PATCH 04/21] Remove old toctree --- triage/issue-tracker.rst | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 87f9d8acdf..d610e7bd45 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -204,19 +204,9 @@ an issue for you in order to properly triage something. This will not only help speed up and simplify your work in helping out, but also help lessen the workload for everyone by gaining your help. -Sub-pages related to the Issue Tracker -====================================== - -.. toctree:: - :maxdepth: 1 - - gh-labels - gh-faq .. seealso:: - | *Issues with Python and documentation* - `The Python issue tracker `_ Where to report issues about Python. From 64236040004c61edb3ec7193de49b82ee5fdbda3 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 19:41:45 +0100 Subject: [PATCH 05/21] Fix image includes --- {images => _static}/python-cyclic-gc-1-new-page.png | Bin {images => _static}/python-cyclic-gc-2-new-page.png | Bin {images => _static}/python-cyclic-gc-3-new-page.png | Bin {images => _static}/python-cyclic-gc-4-new-page.png | Bin {images => _static}/python-cyclic-gc-5-new-page.png | Bin internals/garbage-collector.rst | 10 +++++----- 6 files changed, 5 insertions(+), 5 deletions(-) rename {images => _static}/python-cyclic-gc-1-new-page.png (100%) rename {images => _static}/python-cyclic-gc-2-new-page.png (100%) rename {images => _static}/python-cyclic-gc-3-new-page.png (100%) rename {images => _static}/python-cyclic-gc-4-new-page.png (100%) rename {images => _static}/python-cyclic-gc-5-new-page.png (100%) diff --git a/images/python-cyclic-gc-1-new-page.png b/_static/python-cyclic-gc-1-new-page.png similarity index 100% rename from images/python-cyclic-gc-1-new-page.png rename to _static/python-cyclic-gc-1-new-page.png diff --git a/images/python-cyclic-gc-2-new-page.png b/_static/python-cyclic-gc-2-new-page.png similarity index 100% rename from images/python-cyclic-gc-2-new-page.png rename to _static/python-cyclic-gc-2-new-page.png diff --git a/images/python-cyclic-gc-3-new-page.png b/_static/python-cyclic-gc-3-new-page.png similarity index 100% rename from images/python-cyclic-gc-3-new-page.png rename to _static/python-cyclic-gc-3-new-page.png diff --git a/images/python-cyclic-gc-4-new-page.png b/_static/python-cyclic-gc-4-new-page.png similarity index 100% rename from images/python-cyclic-gc-4-new-page.png rename to _static/python-cyclic-gc-4-new-page.png diff --git a/images/python-cyclic-gc-5-new-page.png b/_static/python-cyclic-gc-5-new-page.png similarity index 100% rename from images/python-cyclic-gc-5-new-page.png rename to _static/python-cyclic-gc-5-new-page.png diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst index 72a054d0b8..e1891bfbee 100644 --- a/internals/garbage-collector.rst +++ b/internals/garbage-collector.rst @@ -181,7 +181,7 @@ of that object when the algorithm starts. This is because the algorithm needs to modify the reference count to do the computations and in this way the interpreter will not modify the real reference count field. -.. figure:: images/python-cyclic-gc-1-new-page.png +.. figure:: /_static/python-cyclic-gc-1-new-page.png The GC then iterates over all containers in the first list and decrements by one the ``gc_ref`` field of any other object that container is referencing. Doing @@ -190,7 +190,7 @@ using the C API or inherited by a superclass) to know what objects are reference each container. After all the objects have been scanned, only the objects that have references from outside the “objects to scan” list will have ``gc_refs > 0``. -.. figure:: images/python-cyclic-gc-2-new-page.png +.. figure:: /_static/python-cyclic-gc-2-new-page.png Notice that having ``gc_refs == 0`` does not imply that the object is unreachable. This is because another object that is reachable from the outside (``gc_refs > 0``) @@ -204,13 +204,13 @@ tentatively unreachable list. The following image depicts the state of the lists moment when the GC processed the ``link_3`` and ``link_4`` objects but has not processed ``link_1`` and ``link_2`` yet. -.. figure:: images/python-cyclic-gc-3-new-page.png +.. figure:: /_static/python-cyclic-gc-3-new-page.png Then the GC scans the next ``link_1`` object. Because it has ``gc_refs == 1``, the gc does not do anything special because it knows it has to be reachable (and is already in what will become the reachable list): -.. figure:: images/python-cyclic-gc-4-new-page.png +.. figure:: /_static/python-cyclic-gc-4-new-page.png When the GC encounters an object which is reachable (``gc_refs > 0``), it traverses its references using the ``tp_traverse`` slot to find all the objects that are @@ -225,7 +225,7 @@ objects that have already been visited once (by unsetting the ``PREV_MASK_COLLEC flag) so that if an object that has already been processed is referenced by some other object, the GC does not process it twice. -.. figure:: images/python-cyclic-gc-5-new-page.png +.. figure:: /_static/python-cyclic-gc-5-new-page.png Notice that an object that was marked as "tentatively unreachable" and was later moved back to the reachable list will be visited again by the garbage collector From 6c2c4bd2dcda2be7d4b14535f66beab579d06785 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 19:53:18 +0100 Subject: [PATCH 06/21] Fix all references --- advanced-tools/clang.rst | 2 + advanced-tools/coverity.rst | 4 +- appendix.rst | 66 +++++++++---------- developer-workflow/communication-channels.rst | 2 + developer-workflow/grammar.rst | 2 +- documentation/help-documenting.rst | 6 +- documentation/start-documenting.rst | 2 +- getting-started/getting-help.rst | 4 +- getting-started/git-boot-camp.rst | 2 + getting-started/pull-request-lifecycle.rst | 3 +- index.rst | 54 +++++++-------- internals/compiler.rst | 2 +- internals/garbage-collector.rst | 1 + testing/buildbots.rst | 4 +- testing/coverage.rst | 2 +- triage/github-bpo-faq.rst | 6 +- triage/issue-tracker.rst | 7 +- triage/labels.rst | 2 +- triage/triaging.rst | 8 +-- 19 files changed, 95 insertions(+), 84 deletions(-) diff --git a/advanced-tools/clang.rst b/advanced-tools/clang.rst index 76afd4786e..74171f0288 100644 --- a/advanced-tools/clang.rst +++ b/advanced-tools/clang.rst @@ -1,3 +1,5 @@ +.. _clang: + *************************** Dynamic Analysis with Clang *************************** diff --git a/advanced-tools/coverity.rst b/advanced-tools/coverity.rst index 5546805176..7c165a3126 100644 --- a/advanced-tools/coverity.rst +++ b/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. diff --git a/appendix.rst b/appendix.rst index dc2a2efe14..296987efae 100644 --- a/appendix.rst +++ b/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` diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index eacf8c1e6f..4d9a061f30 100644 --- a/developer-workflow/communication-channels.rst +++ b/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) ---------------------------------------- diff --git a/developer-workflow/grammar.rst b/developer-workflow/grammar.rst index 471d4e827e..06d1575573 100644 --- a/developer-workflow/grammar.rst +++ b/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. diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 353446d24f..60022d1f17 100644 --- a/documentation/help-documenting.rst +++ b/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 ` for the issue. +* submit a :ref:`pull request ` for the issue. By following the steps in the :ref:`Quick Guide to Pull Requests `, 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 `, you can fork the +To submit a :ref:`pull request `, you can fork the `devguide repo`_ to your GitHub account and clone it using:: $ git clone https://github.com//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 `. You may wish to run ``make check`` +a :ref:`pull request `. You may wish to run ``make check`` and ``make linkcheck`` to make sure that it runs without errors. .. _separate repository: diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index c52a6dc649..588be0dc81 100644 --- a/documentation/start-documenting.rst +++ b/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 `, so you should make +you submit a :ref:`pull request `, so you should make sure that it runs without errors. **On Windows**, a :file:`make.bat` batchfile tries to emulate :command:`make` diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index 5de9c51a0a..f22c225fd9 100644 --- a/getting-started/getting-help.rst +++ b/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 ` 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 `_. .. seealso:: - `Discourse `_ + :ref:`Discourse ` on how to get started. diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index b76271a2b0..cc745ffa17 100644 --- a/getting-started/git-boot-camp.rst +++ b/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 ---------------------------- diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index a10df969b0..e7964df654 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/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 `, 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:: diff --git a/index.rst b/index.rst index 2bf704128f..c30de4798a 100644 --- a/index.rst +++ b/index.rst @@ -42,7 +42,7 @@ instructions please see the :ref:`setup guide `. and the platform-specific pages for :ref:`UNIX `, :ref:`Mac OS `, and :ref:`Windows `. -4. :doc:`Run the tests `:: +4. :ref:`Run the tests `:: ./python -m test -j3 @@ -60,7 +60,7 @@ instructions please see the :ref:`setup guide `. 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 `. 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 ` -* :doc:`coverity` +* :ref:`silencewarnings` +* Fixing issues found by the :ref:`buildbots ` +* :ref:`coverity` * Helping out with reviewing `open pull requests`_. See :ref:`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 `_ (issue tracker for the issue tracker) - * :doc:`experts` + * :ref:`experts` * `Buildbot status`_ * Source code * `Browse online `_ * `Snapshot of the *main* branch `_ * `Daily OS X installer `_ * 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 `_ diff --git a/internals/compiler.rst b/internals/compiler.rst index 2b3e4dd2ca..be39f2cd71 100644 --- a/internals/compiler.rst +++ b/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) diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst index e1891bfbee..c4cecdb79f 100644 --- a/internals/garbage-collector.rst +++ b/internals/garbage-collector.rst @@ -1,4 +1,5 @@ .. _gc: +.. _garbage_collector: Design of CPython's Garbage Collector ===================================== diff --git a/testing/buildbots.rst b/testing/buildbots.rst index 979d4632ea..b3454ee8db 100644 --- a/testing/buildbots.rst +++ b/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 `, 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 ` before +Sometimes, while you have run the :ref:`whole test suite ` 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 diff --git a/testing/coverage.rst b/testing/coverage.rst index d2e4e7f156..919b1081b6 100644 --- a/testing/coverage.rst +++ b/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 `. On the +`issue tracker`_ and submit a :ref:`pull request `. On the issue set the "Components" to "Test" and "Versions" to the version of Python you worked on (i.e., the in-development version). diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index 42b0fb61d4..9f5fd7c950 100644 --- a/triage/github-bpo-faq.rst +++ b/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? diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index d610e7bd45..f4769b042c 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -1,8 +1,9 @@ +.. _tracker: + ============== Issue Tracking ============== -.. _tracker: Using the Issue Tracker ======================= @@ -22,8 +23,8 @@ If you would like to file an issue about this devguide, please do so at the migrated to the current `issue tracker`_ on GitHub. If you're familiar with ``bpo`` and would like to learn more about GitHub - issues, please read this page, and the :doc:`triaging` page as they - provide good introductory material. There is also a :doc:`gh-faq` + issues, please read this page, and the :ref:`triaging` page as they + provide good introductory material. There is also a :ref:`gh-faq` document to answer some of the more popular questions. Checking if a bug already exists diff --git a/triage/labels.rst b/triage/labels.rst index 417c766bbf..95347f9a71 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -1,4 +1,4 @@ -.. _github-labels: +.. _gh-labels: GitHub Labels ============= diff --git a/triage/triaging.rst b/triage/triaging.rst index 9428717a77..07eaa2f4be 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -3,10 +3,10 @@ Triaging an Issue ================= -This section of the devguide documents the `issue tracker`_ for users -and developers. +This section of the devguide documents the :ref:`issue tracker ` for +users and developers. -Contributors with the Triager role on the `issue tracker`_ can triage issues +Contributors with the Triager role on the issue tracker can triage issues directly without any assistance. Additionally, this section provides an overview of the Python triage team. @@ -93,7 +93,7 @@ GitHub Labels for PRs An important component of triaging PRs for the CPython repo involves appropriately categorizing them through the usage of labels. For this -purpose we're using :doc:`gh-labels`. +purpose we're using :ref:`gh-labels`. Applying labels for Issues -------------------------- From 9a77665ee5c1720cafdbe52cf9a3fa7c09c1edc3 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:08:24 +0100 Subject: [PATCH 07/21] Split out triage team from triaging --- core-developers/committing.rst | 9 +- developer-workflow/development-cycle.rst | 2 + triage/index.rst | 1 + triage/issue-tracker.rst | 28 +----- triage/triage-team.rst | 105 +++++++++++++++++++++++ triage/triaging.rst | 79 +---------------- 6 files changed, 115 insertions(+), 109 deletions(-) create mode 100644 triage/triage-team.rst diff --git a/core-developers/committing.rst b/core-developers/committing.rst index 164b2193d8..d4832ebbd2 100644 --- a/core-developers/committing.rst +++ b/core-developers/committing.rst @@ -52,8 +52,8 @@ to enter the public source tree. Ask yourself the following questions: developer can apply the label ``needs backport to X.Y`` to the pull request. Once the backport pull request has been created, remove the ``needs backport to X.Y`` label from the original pull request. (Only - core developers and members of the `Python Triage Team`_ can apply - labels to GitHub pull requests). + core developers and members of the :ref:`Python Triage Team ` + can apply labels to GitHub pull requests). * **Does the pull request pass a check indicating that the submitter has signed the CLA?** Make sure that the contributor has signed a `Contributor @@ -224,11 +224,10 @@ Note that cherry_picker.py_ adds the branch prefix automatically. Once the backport pull request has been created, remove the ``needs backport to X.Y`` label from the original pull request. (Only -core developers and members of the `Python Triage Team`_ can apply -labels to GitHub pull requests). +core developers and members of the :ref:`Python Triage Team ` +can apply labels to GitHub pull requests). .. _cherry_picker.py: https://github.com/python/cherry-picker -.. _`Python Triage Team`: https://devguide.python.org/triaging/#python-triage-team Reverting a merged pull request diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index c20a19713a..460c633d2e 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -273,6 +273,8 @@ who no longer necessitate this level of access will be removed with notice. Multi-Factor Authentication must be enabled by the user in order to remain an Owner of the Python Organization. +.. _current owners: + Current Owners -------------- diff --git a/triage/index.rst b/triage/index.rst index f948cf36bd..b2ae1c5737 100644 --- a/triage/index.rst +++ b/triage/index.rst @@ -9,3 +9,4 @@ Issues and Triaging triaging labels github-bpo-faq + triage-team diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index f4769b042c..0c4d100f7e 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -151,7 +151,7 @@ Python: Python's test suite, having that written can be very helpful. This is all helpful as it allows triagers (i.e., -:ref:`people with the Developer role on the issue tracker `) to +:ref:`people with the Developer role on the issue tracker `) to properly classify an issue so it can be handled by the right core developers in a timely fashion. @@ -168,7 +168,7 @@ by making sure the patch: * includes proper documentation changes * submitter is listed in ``Misc/ACKS``, either already or the patch adds them -Doing all of this allows core developers and :ref:`triagers ` to more +Doing all of this allows core developers and :ref:`triagers` to more quickly look for subtle issues that only people with extensive experience working on Python's code base will notice. @@ -182,30 +182,6 @@ specific kinds of issues (e.g. the "Windows" label if you are a Windows developer, "Extension Modules" if you are familiar with C, etc.). -.. _devrole: - -Gaining the "Triager" Role on the Issue Tracker -=============================================== - -When you have consistently shown the ability to properly -help triage issues without guidance, you may request that you -be given the "Triager" role on the `issue tracker`_. You can make the request -to any person who already has the Triager role. If they decide you are ready -to gain the extra privileges on the tracker they will then act as a mentor to -you until you are ready to do things entirely on your own. There is no set rule -as to how many issues you need to have helped with before or how long you have -been participating. The key requirements are that you show the desire to -help, you are able to work well with others (especially those already with the -Triager role), and that have a firm grasp of how to do things on the issue -tracker properly on your own. - -Gaining the Triager role will allow you to set any value on any issue in the -tracker, releasing you from the burden of having to ask others to set values on -an issue for you in order to properly triage something. This will not only help -speed up and simplify your work in helping out, but also help lessen the -workload for everyone by gaining your help. - - .. seealso:: `The Python issue tracker `_ diff --git a/triage/triage-team.rst b/triage/triage-team.rst new file mode 100644 index 0000000000..4d5aeb7372 --- /dev/null +++ b/triage/triage-team.rst @@ -0,0 +1,105 @@ +.. _triage-team: +.. _triagers: + +=========== +Triage Team +=========== + +The Python triage team is a group dedicated towards improving workflow +efficiency through thoughtful review and triage of open issues and pull +requests. This helps contributors receive timely feedback and enables core +developers to focus on reviewed items which reduces their workload. The +expectations of this role expand upon the "Triager" role on the +:ref:`issue tracker `. The responsibilities listed below are primarily centered +around the Python GitHub repositories. This extends beyond CPython, and, as +needed, to other repos such as devguide and core-workflow. + +Responsibilities include: + +* PR/issue management + - Reviewing PRs + - Assisting contributors + - Notifying appropriate core developers +* Applying appropriate labels to PRs/Issues + - Skip news + - Skip issue + - Good first issue + - Other categorizations + +Although triagers have the power to close PRs, they should generally not do so +without first consulting a core developer. By having triagers and core developers work together, +the author receives a careful consideration of their PR. This encourages future +contributions, regardless of whether their PR is accepted or closed. + +Nonetheless, triagers should feel free to close a PR if they judge that the +chance of the PR being merged would be exceedingly low, even if substantial +revisions were made to the PR. This includes (but is not limited to) the +following: + +* PRs proposing solely cosmetic changes +* PRs proposing changes to deprecated modules +* PRs that are no longer relevant. This includes: + - PRs proposing fixes for bugs that can no longer be reproduced + - PRs proposing changes that have been rejected by Python core developers + elsewhere (e.g. in an issue or a PEP rejection notice) + +If a triager has any doubt about whether to close a PR, they should consult a core +developer before taking any action. + +Triagers can also make use of the ``invalid`` and ``stale`` labels to suggest that a +PR may be suitable for closure. For more information, see the +:ref:`GitHub PR labels ` section. + +Note that it is of paramount importance to treat every contributor to the Python +project kindly and with respect. Regardless of whether they're entirely new +or a veteran core developer, they're actively choosing to voluntarily donate their +time towards the improvement of Python. As is the case with any member of +the Python Software Foundation, always follow the `PSF Code of Conduct`_. + +.. _PSF Code of Conduct: https://www.python.org/psf/conduct/ + + +Becoming a member of the Python triage team +=========================================== + +Any Python core developers are welcome to invite a Python contributor to the +Python triage team. Triagers will be responsible to handle not just issues, but +also pull requests, and even managing backports. A Python triager has access to +more repositories than just CPython. + +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, and the core developer can pass the request to the `Python +organization admin +`_ +on GitHub. The request can be made confidentially via a DM in Discourse, or +publicly by opening an `issue in the core-workflow repository +`_. + +For every new triager, it would be great to announce them in the python-committers +mailing list and core-workflow category in Discourse. `Example announcement +`_. + + +Gaining the "Triager" Role on the Issue Tracker +=============================================== + +When you have consistently shown the ability to properly +help triage issues without guidance, you may request that you +be given the "Triager" role on the `issue tracker`_. You can make the request +to any person who already has the Triager role. If they decide you are ready +to gain the extra privileges on the tracker they will then act as a mentor to +you until you are ready to do things entirely on your own. There is no set rule +as to how many issues you need to have helped with before or how long you have +been participating. The key requirements are that you show the desire to +help, you are able to work well with others (especially those already with the +Triager role), and that have a firm grasp of how to do things on the issue +tracker properly on your own. + +Gaining the Triager role will allow you to set any value on any issue in the +tracker, releasing you from the burden of having to ask others to set values on +an issue for you in order to properly triage something. This will not only help +speed up and simplify your work in helping out, but also help lessen the +workload for everyone by gaining your help. + +.. _issue tracker: https://devguide.python.org/tracker/ diff --git a/triage/triaging.rst b/triage/triaging.rst index 07eaa2f4be..7016f4efa7 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -9,87 +9,10 @@ users and developers. Contributors with the Triager role on the issue tracker can triage issues directly without any assistance. -Additionally, this section provides an overview of the Python triage team. - -Python triage team ------------------- - -The Python triage team is a group dedicated towards improving workflow -efficiency through thoughtful review and triage of open issues and pull -requests. This helps contributors receive timely feedback and enables core -developers to focus on reviewed items which reduces their workload. The -expectations of this role expand upon the "Triager" role on the -`issue tracker`_. The responsibilities listed below are primarily centered -around the Python GitHub repositories. This extends beyond CPython, and, as -needed, to other repos such as devguide and core-workflow. - -Responsibilities include: - -* PR/issue management - - Reviewing PRs - - Assisting contributors - - Notifying appropriate core developers -* Applying appropriate labels to PRs/Issues - - Skip news - - Skip issue - - Good first issue - - Other categorizations - -Although triagers have the power to close PRs, they should generally not do so -without first consulting a core developer. By having triagers and core developers work together, -the author receives a careful consideration of their PR. This encourages future -contributions, regardless of whether their PR is accepted or closed. - -Nonetheless, triagers should feel free to close a PR if they judge that the -chance of the PR being merged would be exceedingly low, even if substantial -revisions were made to the PR. This includes (but is not limited to) the -following: - -* PRs proposing solely cosmetic changes -* PRs proposing changes to deprecated modules -* PRs that are no longer relevant. This includes: - - PRs proposing fixes for bugs that can no longer be reproduced - - PRs proposing changes that have been rejected by Python core developers - elsewhere (e.g. in an issue or a PEP rejection notice) - -If a triager has any doubt about whether to close a PR, they should consult a core -developer before taking any action. - -Triagers can also make use of the ``invalid`` and ``stale`` labels to suggest that a -PR may be suitable for closure. For more information, see the -:ref:`GitHub PR labels ` section. - -Note that it is of paramount importance to treat every contributor to the Python -project kindly and with respect. Regardless of whether they're entirely new -or a veteran core developer, they're actively choosing to voluntarily donate their -time towards the improvement of Python. As is the case with any member of -the Python Software Foundation, always follow the `PSF Code of Conduct`_. - -Becoming a member of the Python triage team -------------------------------------------- - -Any Python core developers are welcome to invite a Python contributor to the -Python triage team. Triagers will be responsible to handle not just issues, but -also pull requests, and even managing backports. A Python triager has access to -more repositories than just CPython. - -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, and the core developer can pass the request to the `Python -organization admin -`_ -on GitHub. The request can be made confidentially via a DM in Discourse, or -publicly by opening an `issue in the core-workflow repository -`_. - -For every new triager, it would be great to announce them in the python-committers -mailing list and core-workflow category in Discourse. `Example announcement -`_. - .. _github-pr-labels: GitHub Labels for PRs -''''''''''''''''''''' +--------------------- An important component of triaging PRs for the CPython repo involves appropriately categorizing them through the usage of labels. For this From 5843de039d27fd02c53553fe9cac1999398fc46f Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:13:28 +0100 Subject: [PATCH 08/21] Combine the two 'become a triager' sections --- triage/triage-team.rst | 37 ++++++++++++++++--------------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/triage/triage-team.rst b/triage/triage-team.rst index 4d5aeb7372..36994cd72e 100644 --- a/triage/triage-team.rst +++ b/triage/triage-team.rst @@ -62,32 +62,15 @@ the Python Software Foundation, always follow the `PSF Code of Conduct`_. Becoming a member of the Python triage team =========================================== -Any Python core developers are welcome to invite a Python contributor to the +All Python core developers are welcome to invite a Python contributor to the Python triage team. Triagers will be responsible to handle not just issues, but also pull requests, and even managing backports. A Python triager has access to more repositories than just CPython. -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, and the core developer can pass the request to the `Python -organization admin -`_ -on GitHub. The request can be made confidentially via a DM in Discourse, or -publicly by opening an `issue in the core-workflow repository -`_. - -For every new triager, it would be great to announce them in the python-committers -mailing list and core-workflow category in Discourse. `Example announcement -`_. - - -Gaining the "Triager" Role on the Issue Tracker -=============================================== - When you have consistently shown the ability to properly help triage issues without guidance, you may request that you -be given the "Triager" role on the `issue tracker`_. You can make the request -to any person who already has the Triager role. If they decide you are ready +be given the "Triager" role on the :ref:`issue tracker `. You can make the request +to any core developer. If they decide you are ready to gain the extra privileges on the tracker they will then act as a mentor to you until you are ready to do things entirely on your own. There is no set rule as to how many issues you need to have helped with before or how long you have @@ -102,4 +85,16 @@ an issue for you in order to properly triage something. This will not only help speed up and simplify your work in helping out, but also help lessen the workload for everyone by gaining your help. -.. _issue tracker: https://devguide.python.org/tracker/ +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 devloper 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 python-committers +mailing list and core-workflow category in Discourse. `Example announcement +`_. From 8ba4c9b486365ebe64377dcaec8aba9fda8af46e Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:24:51 +0100 Subject: [PATCH 09/21] Move labels content to gh-labels --- triage/labels.rst | 241 ++++++++++++++++++++++++++++++++++++++++ triage/triaging.rst | 261 -------------------------------------------- 2 files changed, 241 insertions(+), 261 deletions(-) diff --git a/triage/labels.rst b/triage/labels.rst index 95347f9a71..ca6fb6787f 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -168,3 +168,244 @@ test-with-buildbots PRs with large code changes requiring more testing before merging. This may take multiple hours to complete. Triagers can also stop a stuck build using the web interface. + + +.. _github-pr-labels: + +GitHub Labels for PRs +--------------------- + +An important component of triaging PRs for the CPython repo involves +appropriately categorizing them through the usage of labels. For this +purpose we're using :ref:`gh-labels`. + +Applying labels for Issues +-------------------------- + +The major elements found in an issue report include: + +* Classification (including *Title*) - Metadata that lets us categorize + the issue. Apart from the *Title* field, we use some *type-*, *component-*, and + *version-* specific labels. +* Process - These fields indicate the state of the issue and its progress + toward resolution. The fields are *Status* (open/closed), *Assignees*, + *Comment*, as well as *priority-* and *keyword-* specific labels. +* Messages +* History + +Title +''''' +A brief description of the issue. Review whether the title is too generic or +specifies an incorrect term or library. + +(Optional) Add a prefix at the start of the title to indicate the module, e.g. +IDLE, doc, or asyncio. + +Type +'''' +Describes the type of issue. If an issue does not fit within any +specific type, please do not set a type. + ++----------------+----------------------------------------------------------+ +| Type | Description | ++================+==========================================================+ +| behavior | Unexpected behavior, result, or exception. Most bugs | +| | will have this type. This group also includes compile | +| | errors, and crashers. | ++----------------+----------------------------------------------------------+ +| enhancement | Issues that propose the addition of new functionality, | +| | such as new functions, classes, modules, or even new | +| | arguments for existing functions. Also used for | +| | improvements in the documentation, test suite and | +| | other refactorings. A good place to discuss enhancements | +| | prior to filing an issue is `python-ideas`_ mailing | +| | list. | ++----------------+----------------------------------------------------------+ +| performance | Situations where too much time is necessary to complete | +| | the task. For example, a common task now takes | +| | significantly longer to complete. This group also | +| | includes resource usage (e.g. too much memory needed) | +| | issues. | ++----------------+----------------------------------------------------------+ +| security | Issues that might have security implications. Report | +| | security vulnerabilities using the procedure found in | +| | the `Reporting security issues in Python`_ page on the | +| | python.org website. | ++----------------+----------------------------------------------------------+ + +Stage +''''' +A needed next action to advance the issue. The *stage* on GitHub issues is +determined by presence of a linked PR and whether the issue is still open +or closed. It is the PR that holds code review-related labels. + +Components +'''''''''' +The area or Python library affected by the issue. A single issue can apply +multiple component labels. + +One or more components may be selected for an issue: + ++-------------------+------------------------------------------------------+ +| Component | Description | ++===================+======================================================+ +| Documentation | The documentation in Doc_ (source used to build HTML | +| | docs for https://docs.python.org/). | ++-------------------+------------------------------------------------------+ +| Extension Modules | C modules in Modules_. | ++-------------------+------------------------------------------------------+ +| Interpreter Core | The interpreter core. | +| | The built-in objects in `Objects`_, the `Python`_, | +| | `Grammar`_ and `Parser`_ dirs. | ++-------------------+------------------------------------------------------+ +| Library (Lib) | Python modules in Lib_. | ++-------------------+------------------------------------------------------+ +| Tests | The unittest framework in `Lib/unittest`_ | +| | The doctest framework `Lib/doctest.py`_. | +| | The CPython tests in `Lib/test`_. | +| | The test runner in `Lib/test/regrtest.py`_. | +| | The test support utilities in `Lib/test/support`_. | ++-------------------+------------------------------------------------------+ + +Versions +'''''''' +The known versions of Python that the issue affects and should be fixed for. + +Thus if an issue for a new feature is assigned for e.g., Python 3.8 but is not +applied before Python 3.8.0 is released, this label should be updated to say +``python-3.9`` as the version and drop ``python-3.8``. + +Priority +'''''''' +What is the severity and urgency? + ++------------------+--------------------------------------------------------+ +| Priority | Description | ++==================+========================================================+ +| normal | The default value for most issues filed. | ++------------------+--------------------------------------------------------+ +| deferred blocker | The issue will not hold up the next release, *n*. It | +| | will be promoted to a *release blocker* for the | +| | following release, *n+1*. | ++------------------+--------------------------------------------------------+ +| release blocker | The issue **must** be fixed before *any* release is | +| | made, e.g., will block the next release even if it is | +| | an alpha release. | ++------------------+--------------------------------------------------------+ + +As a guideline, whether a bug is a *release blocker* for the current +:ref:`release schedule ` is decided by the release manager. +Triagers may recommend this priority and should notify the release manager by +tagging them in a comment using ``@username``. If needed, consult the +:ref:`release schedule ` and the release's associated PEP for the +release manager's name. + +Keywords +'''''''' +Various informational flags about the issue. Multiple values are possible. + ++---------------+------------------------------------------------------------+ +| Keyword | Description | ++===============+============================================================+ +| easy | Fixing the issue should not take longer than a day for | +| | someone new to contributing to Python to solve. | ++---------------+------------------------------------------------------------+ + +Nosy List +''''''''' +A list of people who may be interested in an issue. + +This used to be a feature of the old issue tracker. On GitHub issues the +same effect is achieved by tagging people in a comment using ``@username``. + +It is acceptable to tag someone to if you think the issue should be brought to +their attention. Use the :ref:`experts` to know who wants to be added to the +nosy list for issues targeting specific areas. + +If you want to subscribe yourself to an issue, click the *🔔 Subscribe* +button in the sidebar. Similarly, if you were tagged by somebody else but +decided this issue is not for you, you might click the *🔕 Unsubscribe* +button in the sidebar. + +Assignees +''''''''' +Who is expected to take the next step in resolving the issue. + +It is acceptable to assign an issue to someone if the issue cannot move +forward without their help, e.g., they need to make a technical decision to +allow the issue to move forward. Also consult the :ref:`experts` as certain +stdlib modules should always be assigned to a specific person. + +Note that in order to assign an issue to someone, that person **must** be +a team member, likely a Triager or a core developer. + +Dependencies +'''''''''''' +The issue requires the listed issue(s) to be resolved first before it can move +forward. This is achieved using checkbox lists in the initial issue description +comment. Long story short, if you add this:: + + - [x] #739 + - [ ] https://github.com/octo-org/octo-repo/issues/740 + - [ ] Add delight to the experience when all tasks are complete :tada: + +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 +`_. + +Superseder +'''''''''' +The issue is a duplicate of the listed issue(s). To make GitHub mark +an issue as duplicate, write "Duplicate of #xxxx" in a comment. + +Status +'''''' + ++---------------+------------------------------------------------------------+ +| Status | Description | ++===============+============================================================+ +| open | Issue is not resolved. | ++---------------+------------------------------------------------------------+ +| closed | The issue has been resolved (somehow). | ++---------------+------------------------------------------------------------+ + +Linked pull requests +'''''''''''''''''''' +A link might be added manually using the cog icon next to this field. +Most commonly though, if the PR includes "Fixes #xxx" in its description, +the link will be added automatically. + +Generating Special Links in a Comment +------------------------------------- +Using the following abbreviations in a comment will automatically generate +a link to relevant web pages. + ++-------------------------------------------------------------+-------------------------------------------------------+ +| Comment abbreviation | Description | ++=============================================================+=======================================================+ +| ``#``, | Links to the tracker issue or PR ```` (they | +| ``GH-`` | share the same sequence of integers on GitHub). | ++-------------------------------------------------------------+-------------------------------------------------------+ +| ``BPO-`` | Links to the old bug tracker at bugs.python.org. | ++-------------------------------------------------------------+-------------------------------------------------------+ +| a 10-, 11-, 12-, or 40-digit hex ```` | Indicates a Git changeset identifier and | +| | generates a link to changeset ```` on GitHub. | ++-------------------------------------------------------------+-------------------------------------------------------+ + +.. _Doc: https://github.com/python/cpython/tree/main/Doc/ +.. _Grammar: https://github.com/python/cpython/tree/main/Grammar/ +.. _Lib: https://github.com/python/cpython/tree/main/Lib/ +.. _Lib/doctest.py: https://github.com/python/cpython/blob/main/Lib/doctest.py +.. _Lib/test: https://github.com/python/cpython/tree/main/Lib/test/ +.. _Lib/test/regrtest.py: https://github.com/python/cpython/blob/main/Lib/test/regrtest.py +.. _Lib/test/support: https://github.com/python/cpython/tree/main/Lib/test/support/ +.. _Lib/unittest: https://github.com/python/cpython/tree/main/Lib/unittest/ +.. _Modules: https://github.com/python/cpython/tree/main/Modules/ +.. _Objects: https://github.com/python/cpython/tree/main/Objects/ +.. _Parser: https://github.com/python/cpython/tree/main/Parser/ +.. _Python: https://github.com/python/cpython/tree/main/Python/ +.. _Reporting security issues in Python: https://www.python.org/dev/security/ +.. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org diff --git a/triage/triaging.rst b/triage/triaging.rst index 7016f4efa7..ef8be9baf4 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -9,229 +9,6 @@ users and developers. Contributors with the Triager role on the issue tracker can triage issues directly without any assistance. -.. _github-pr-labels: - -GitHub Labels for PRs ---------------------- - -An important component of triaging PRs for the CPython repo involves -appropriately categorizing them through the usage of labels. For this -purpose we're using :ref:`gh-labels`. - -Applying labels for Issues --------------------------- - -The major elements found in an issue report include: - -* Classification (including *Title*) - Metadata that lets us categorize - the issue. Apart from the *Title* field, we use some *type-*, *component-*, and - *version-* specific labels. -* Process - These fields indicate the state of the issue and its progress - toward resolution. The fields are *Status* (open/closed), *Assignees*, - *Comment*, as well as *priority-* and *keyword-* specific labels. -* Messages -* History - -Title -''''' -A brief description of the issue. Review whether the title is too generic or -specifies an incorrect term or library. - -(Optional) Add a prefix at the start of the title to indicate the module, e.g. -IDLE, doc, or asyncio. - -Type -'''' -Describes the type of issue. If an issue does not fit within any -specific type, please do not set a type. - -+----------------+----------------------------------------------------------+ -| Type | Description | -+================+==========================================================+ -| behavior | Unexpected behavior, result, or exception. Most bugs | -| | will have this type. This group also includes compile | -| | errors, and crashers. | -+----------------+----------------------------------------------------------+ -| enhancement | Issues that propose the addition of new functionality, | -| | such as new functions, classes, modules, or even new | -| | arguments for existing functions. Also used for | -| | improvements in the documentation, test suite and | -| | other refactorings. A good place to discuss enhancements | -| | prior to filing an issue is `python-ideas`_ mailing | -| | list. | -+----------------+----------------------------------------------------------+ -| performance | Situations where too much time is necessary to complete | -| | the task. For example, a common task now takes | -| | significantly longer to complete. This group also | -| | includes resource usage (e.g. too much memory needed) | -| | issues. | -+----------------+----------------------------------------------------------+ -| security | Issues that might have security implications. Report | -| | security vulnerabilities using the procedure found in | -| | the `Reporting security issues in Python`_ page on the | -| | python.org website. | -+----------------+----------------------------------------------------------+ - -Stage -''''' -A needed next action to advance the issue. The *stage* on GitHub issues is -determined by presence of a linked PR and whether the issue is still open -or closed. It is the PR that holds code review-related labels. - -Components -'''''''''' -The area or Python library affected by the issue. A single issue can apply -multiple component labels. - -One or more components may be selected for an issue: - -+-------------------+------------------------------------------------------+ -| Component | Description | -+===================+======================================================+ -| Documentation | The documentation in Doc_ (source used to build HTML | -| | docs for https://docs.python.org/). | -+-------------------+------------------------------------------------------+ -| Extension Modules | C modules in Modules_. | -+-------------------+------------------------------------------------------+ -| Interpreter Core | The interpreter core. | -| | The built-in objects in `Objects`_, the `Python`_, | -| | `Grammar`_ and `Parser`_ dirs. | -+-------------------+------------------------------------------------------+ -| Library (Lib) | Python modules in Lib_. | -+-------------------+------------------------------------------------------+ -| Tests | The unittest framework in `Lib/unittest`_ | -| | The doctest framework `Lib/doctest.py`_. | -| | The CPython tests in `Lib/test`_. | -| | The test runner in `Lib/test/regrtest.py`_. | -| | The test support utilities in `Lib/test/support`_. | -+-------------------+------------------------------------------------------+ - -Versions -'''''''' -The known versions of Python that the issue affects and should be fixed for. - -Thus if an issue for a new feature is assigned for e.g., Python 3.8 but is not -applied before Python 3.8.0 is released, this label should be updated to say -``python-3.9`` as the version and drop ``python-3.8``. - -Priority -'''''''' -What is the severity and urgency? - -+------------------+--------------------------------------------------------+ -| Priority | Description | -+==================+========================================================+ -| normal | The default value for most issues filed. | -+------------------+--------------------------------------------------------+ -| deferred blocker | The issue will not hold up the next release, *n*. It | -| | will be promoted to a *release blocker* for the | -| | following release, *n+1*. | -+------------------+--------------------------------------------------------+ -| release blocker | The issue **must** be fixed before *any* release is | -| | made, e.g., will block the next release even if it is | -| | an alpha release. | -+------------------+--------------------------------------------------------+ - -As a guideline, whether a bug is a *release blocker* for the current `release -schedule`_ is decided by the release manager. Triagers may recommend this -priority and should notify the release manager by tagging them in a comment -using ``@username``. If needed, consult the `release schedule`_ and the -release's associated PEP for the release manager's name. - -Keywords -'''''''' -Various informational flags about the issue. Multiple values are possible. - -+---------------+------------------------------------------------------------+ -| Keyword | Description | -+===============+============================================================+ -| easy | Fixing the issue should not take longer than a day for | -| | someone new to contributing to Python to solve. | -+---------------+------------------------------------------------------------+ - -Nosy List -''''''''' -A list of people who may be interested in an issue. - -This used to be a feature of the old issue tracker. On GitHub issues the -same effect is achieved by tagging people in a comment using ``@username``. - -It is acceptable to tag someone to if you think the issue should be brought to -their attention. Use the :ref:`experts` to know who wants to be added to the -nosy list for issues targeting specific areas. - -If you want to subscribe yourself to an issue, click the *🔔 Subscribe* -button in the sidebar. Similarly, if you were tagged by somebody else but -decided this issue is not for you, you might click the *🔕 Unsubscribe* -button in the sidebar. - -Assignees -''''''''' -Who is expected to take the next step in resolving the issue. - -It is acceptable to assign an issue to someone if the issue cannot move -forward without their help, e.g., they need to make a technical decision to -allow the issue to move forward. Also consult the :ref:`experts` as certain -stdlib modules should always be assigned to a specific person. - -Note that in order to assign an issue to someone, that person **must** be -a team member, likely a Triager or a core developer. - -Dependencies -'''''''''''' -The issue requires the listed issue(s) to be resolved first before it can move -forward. This is achieved using checkbox lists in the initial issue description -comment. Long story short, if you add this:: - - - [x] #739 - - [ ] https://github.com/octo-org/octo-repo/issues/740 - - [ ] Add delight to the experience when all tasks are complete :tada: - -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 -`_. - -Superseder -'''''''''' -The issue is a duplicate of the listed issue(s). To make GitHub mark -an issue as duplicate, write "Duplicate of #xxxx" in a comment. - -Status -'''''' - -+---------------+------------------------------------------------------------+ -| Status | Description | -+===============+============================================================+ -| open | Issue is not resolved. | -+---------------+------------------------------------------------------------+ -| closed | The issue has been resolved (somehow). | -+---------------+------------------------------------------------------------+ - -Linked pull requests -'''''''''''''''''''' -A link might be added manually using the cog icon next to this field. -Most commonly though, if the PR includes "Fixes #xxx" in its description, -the link will be added automatically. - -Generating Special Links in a Comment -------------------------------------- -Using the following abbreviations in a comment will automatically generate -a link to relevant web pages. - -+-------------------------------------------------------------+-------------------------------------------------------+ -| Comment abbreviation | Description | -+=============================================================+=======================================================+ -| ``#``, | Links to the tracker issue or PR ```` (they | -| ``GH-`` | share the same sequence of integers on GitHub). | -+-------------------------------------------------------------+-------------------------------------------------------+ -| ``BPO-`` | Links to the old bug tracker at bugs.python.org. | -+-------------------------------------------------------------+-------------------------------------------------------+ -| a 10-, 11-, 12-, or 40-digit hex ```` | Indicates a Git changeset identifier and | -| | generates a link to changeset ```` on GitHub. | -+-------------------------------------------------------------+-------------------------------------------------------+ Checklist for Triaging ---------------------- @@ -255,41 +32,3 @@ Checklist for Triaging - Keywords * (Optional) Leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. - - -.. _CPython: https://github.com/python/cpython/ -.. _Doc: https://github.com/python/cpython/tree/main/Doc/ -.. _Grammar: https://github.com/python/cpython/tree/main/Grammar/ -.. _Lib: https://github.com/python/cpython/tree/main/Lib/ -.. _Lib/lib2to3: https://github.com/python/cpython/tree/main/Lib/lib2to3/ -.. _Lib/ctypes: https://github.com/python/cpython/tree/main/Lib/ctypes/ -.. _Lib/distutils: https://github.com/python/cpython/tree/main/Lib/distutils/ -.. _Lib/doctest.py: https://github.com/python/cpython/blob/main/Lib/doctest.py -.. _Lib/idlelib: https://github.com/python/cpython/tree/main/Lib/idlelib/ -.. _Lib/io.py: https://github.com/python/cpython/blob/main/Lib/io.py -.. _Lib/re.py: https://github.com/python/cpython/blob/main/Lib/re.py -.. _Lib/test: https://github.com/python/cpython/tree/main/Lib/test/ -.. _Lib/test/regrtest.py: https://github.com/python/cpython/blob/main/Lib/test/regrtest.py -.. _Lib/test/support: https://github.com/python/cpython/tree/main/Lib/test/support/ -.. _Lib/tkinter: https://github.com/python/cpython/tree/main/Lib/tkinter/ -.. _Lib/unittest: https://github.com/python/cpython/tree/main/Lib/unittest/ -.. _Lib/xml: https://github.com/python/cpython/tree/main/Lib/xml/ -.. _Modules: https://github.com/python/cpython/tree/main/Modules/ -.. _Modules/_io: https://github.com/python/cpython/tree/main/Modules/_io/ -.. _Modules/_sre.c: https://github.com/python/cpython/blob/main/Modules/_sre.c -.. _Objects: https://github.com/python/cpython/tree/main/Objects/ -.. _Objects/unicodeobject.c: https://github.com/python/cpython/blob/main/Objects/unicodeobject.c -.. _Parser: https://github.com/python/cpython/tree/main/Parser/ -.. _Python: https://github.com/python/cpython/tree/main/Python/ -.. _Tools: https://github.com/python/cpython/tree/main/Tools/ -.. _Tools/demo: https://github.com/python/cpython/tree/main/Tools/demo/ -.. _Developer's guide: https://github.com/python/devguide/ -.. _GSoC: https://summerofcode.withgoogle.com/ -.. _issue tracker: https://devguide.python.org/tracker/ -.. _GitHub pull requests: https://github.com/python/cpython/pulls -.. _Python source code repositories: https://github.com/python/cpython/ -.. _Reporting security issues in Python: https://www.python.org/dev/security/ -.. _python-ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org -.. _release schedule: https://devguide.python.org/#status-of-python-branches -.. _PSF Code of Conduct: https://www.python.org/psf/conduct/ -.. _PEP 3121: https://www.python.org/dev/peps/pep-3121/ From 8ef2a190491c9fc04d29dfdab11fa1dc4c4ebdff Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:26:17 +0100 Subject: [PATCH 10/21] Move "Helping Triage Issues" to triaging --- triage/issue-tracker.rst | 68 ----------------------------------- triage/triaging.rst | 77 ++++++++++++++++++++++++++++++++++++++-- 2 files changed, 74 insertions(+), 71 deletions(-) diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 0c4d100f7e..a848ea3f11 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -114,74 +114,6 @@ As a reminder, issues closed by a core developer have already been carefully considered. Please do not reopen a closed issue. An issue can be closed with reason either as ``complete`` or ``not planned``. -.. _helptriage: - -Helping Triage Issues -===================== - -Once you know your way around how Python's source files are -structured and you are comfortable working with patches, a great way to -contribute is to help triage issues. Do realize, though, that experience -working on Python is needed in order to effectively help triage. - -Around the clock, new issues are being opened on the `issue tracker`_ and -existing issues are being updated. Every issue needs to be triaged to make -sure various things are in proper order. Even without special privileges you -can help with this process. - -Classifying Reports -------------------- - -For bugs, an issue needs to: - -* clearly explain the bug so it can be reproduced -* include all relevant platform details -* state what version(s) of Python are affected by the bug. - -These are things you can help with once you have experience developing for -Python: - -* try reproducing the bug: For instance, if a bug is not clearly explained - enough for you to reproduce it then there is a good chance a core developer - won't be able to either. -* see if the issue happens on a different Python version: It is always helpful - to know if a bug not only affects the in-development version of Python, but - whether it also affects other versions in maintenance mode. -* write a unit test: If the bug lacks a unit test that should end up in - Python's test suite, having that written can be very helpful. - -This is all helpful as it allows triagers (i.e., -:ref:`people with the Developer role on the issue tracker `) to -properly classify an issue so it can be handled by the right core developers in -a timely fashion. - -Reviewing Patches ------------------ - -If an issue has a pull request attached that has not been reviewed, you can help -by making sure the patch: - -* follows the style guides -* applies cleanly to an up-to-date clone -* is a good solution to the problem it is trying to solve -* includes proper tests -* includes proper documentation changes -* submitter is listed in ``Misc/ACKS``, either already or the patch adds them - -Doing all of this allows core developers and :ref:`triagers` to more -quickly look for subtle issues that only people with extensive experience -working on Python's code base will notice. - -Finding an Issue You Can Help With ----------------------------------- - -If you want to help triage issues, you might also want to search for issues -in modules which you have a working knowledge. Search for the name of a module -in the issue tracker or use the `advanced search`_ query builder to search for -specific kinds of issues (e.g. the "Windows" label if you are a Windows -developer, "Extension Modules" if you are familiar with C, etc.). - - .. seealso:: `The Python issue tracker `_ diff --git a/triage/triaging.rst b/triage/triaging.rst index ef8be9baf4..069afb786b 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -1,7 +1,8 @@ .. _triaging: -Triaging an Issue -================= +=================== + Triaging an Issue +=================== This section of the devguide documents the :ref:`issue tracker ` for users and developers. @@ -11,7 +12,7 @@ directly without any assistance. Checklist for Triaging ----------------------- +====================== * Read the issue comment(s). * Review and set classification fields @@ -32,3 +33,73 @@ Checklist for Triaging - Keywords * (Optional) Leave a brief comment about the proposed next action needed. If there is a long message list, a summary can be very helpful. + + +.. _helptriage: + +Helping Triage Issues +===================== + +Once you know your way around how Python's source files are +structured and you are comfortable working with patches, a great way to +contribute is to help triage issues. Do realize, though, that experience +working on Python is needed in order to effectively help triage. + +Around the clock, new issues are being opened on the :ref:`issue tracker +` and existing issues are being updated. Every issue needs to be +triaged to make sure various things are in proper order. Even without special +privileges you can help with this process. + +Classifying Reports +------------------- + +For bugs, an issue needs to: + +* clearly explain the bug so it can be reproduced +* include all relevant platform details +* state what version(s) of Python are affected by the bug. + +These are things you can help with once you have experience developing for +Python: + +* try reproducing the bug: For instance, if a bug is not clearly explained + enough for you to reproduce it then there is a good chance a core developer + won't be able to either. +* see if the issue happens on a different Python version: It is always helpful + to know if a bug not only affects the in-development version of Python, but + whether it also affects other versions in maintenance mode. +* write a unit test: If the bug lacks a unit test that should end up in + Python's test suite, having that written can be very helpful. + +This is all helpful as it allows triagers (i.e., +:ref:`people with the Developer role on the issue tracker `) to +properly classify an issue so it can be handled by the right core developers in +a timely fashion. + +Reviewing Patches +----------------- + +If an issue has a pull request attached that has not been reviewed, you can help +by making sure the patch: + +* follows the style guides +* applies cleanly to an up-to-date clone +* is a good solution to the problem it is trying to solve +* includes proper tests +* includes proper documentation changes +* submitter is listed in ``Misc/ACKS``, either already or the patch adds them + +Doing all of this allows core developers and :ref:`triagers` to more +quickly look for subtle issues that only people with extensive experience +working on Python's code base will notice. + +Finding an Issue You Can Help With +---------------------------------- + +If you want to help triage issues, you might also want to search for issues +in modules which you have a working knowledge. Search for the name of a module +in the issue tracker or use the `advanced search`_ query builder to search for +specific kinds of issues (e.g. the "Windows" label if you are a Windows +developer, "Extension Modules" if you are familiar with C, etc.). + +.. _advanced search: https://github.com/search/advanced From 55187d02dec882df009604da1ab9420081d75ac8 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:35:53 +0100 Subject: [PATCH 11/21] Split out style guide --- documentation/index.rst | 1 + documentation/start-documenting.rst | 225 +--------------------------- documentation/style-guide.rst | 220 +++++++++++++++++++++++++++ 3 files changed, 227 insertions(+), 219 deletions(-) create mode 100644 documentation/style-guide.rst diff --git a/documentation/index.rst b/documentation/index.rst index 8213b0ceda..be441935a2 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -7,3 +7,4 @@ Documentation start-documenting help-documenting + style-guide diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 588be0dc81..39a4eb4adf 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -59,224 +59,6 @@ gladly work with you to integrate your text, dealing with the markup for you. Please don't let the material in this document stand between the documentation and your desire to help out! -.. _style-guide: - -Style guide -=========== - -Use of whitespace ------------------ - -All reST files use an indentation of 3 spaces; no tabs are allowed. The -maximum line length is 80 characters for normal text, but tables, deeply -indented code samples and long links may extend beyond that. Code example -bodies should use normal Python 4-space indentation. - -Make generous use of blank lines where applicable; they help group things -together. - -A sentence-ending period may be followed by one or two spaces; while reST -ignores the second space, it is customarily put in by some users, for example -to aid Emacs' auto-fill mode. - -Footnotes ---------- - -Footnotes are generally discouraged, though they may be used when they are the -best way to present specific information. When a footnote reference is added at -the end of the sentence, it should follow the sentence-ending punctuation. The -reST markup should appear something like this:: - - This sentence has a footnote reference. [#]_ This is the next sentence. - -Footnotes should be gathered at the end of a file, or if the file is very long, -at the end of a section. The docutils will automatically create backlinks to -the footnote reference. - -Footnotes may appear in the middle of sentences where appropriate. - -Capitalization --------------- - -.. sidebar:: Sentence case - - Sentence case is a set of capitalization rules used in English - sentences: the first word is always capitalized and other words are - only capitalized if there is a specific rule requiring it. - -In the Python documentation, the use of sentence case in section titles is -preferable, but consistency within a unit is more important than -following this rule. If you add a section to a chapter where most -sections are in title case, you can either convert all titles to -sentence case or use the dominant style in the new section title. - -Sentences that start with a word for which specific rules require -starting it with a lower case letter should be avoided. - -.. note:: - - Sections that describe a library module often have titles in the - form of "modulename --- Short description of the module." In this - case, the description should be capitalized as a stand-alone - sentence. - -Many special names are used in the Python documentation, including the names of -operating systems, programming languages, standards bodies, and the like. Most -of these entities are not assigned any special markup, but the preferred -spellings are given here to aid authors in maintaining the consistency of -presentation in the Python documentation. - -Other terms and words deserve special mention as well; these conventions should -be used to ensure consistency throughout the documentation: - -CPU - For "central processing unit." Many style guides say this should be - spelled out on the first use (and if you must use it, do so!). For - the Python documentation, this abbreviation should be avoided since - there's no reasonable way to predict which occurrence will be the - first seen by the reader. It is better to use the word "processor" - instead. - -POSIX - The name assigned to a particular group of standards. This is always - uppercase. - -Python - The name of our favorite programming language is always capitalized. - -reST - For "reStructuredText," an easy to read, plaintext markup syntax - used to produce Python documentation. When spelled out, it is - always one word and both forms start with a lower case 'r'. - -Unicode - The name of a character coding system. This is always written - capitalized. - -Unix - The name of the operating system developed at AT&T Bell Labs in the early - 1970s. - -Affirmative Tone ----------------- - -The documentation focuses on affirmatively stating what the language does and -how to use it effectively. - -Except for certain security or segfault risks, the docs should avoid -wording along the lines of "feature x is dangerous" or "experts only". These -kinds of value judgments belong in external blogs and wikis, not in the core -documentation. - -Bad example (creating worry in the mind of a reader): - - Warning: failing to explicitly close a file could result in lost data or - excessive resource consumption. Never rely on reference counting to - automatically close a file. - -Good example (establishing confident knowledge in the effective use of the -language): - - A best practice for using files is use a try/finally pair to explicitly - close a file after it is used. Alternatively, using a with-statement can - achieve the same effect. This assures that files are flushed and file - descriptor resources are released in a timely manner. - -Economy of Expression ---------------------- - -More documentation is not necessarily better documentation. Err on the side -of being succinct. - -It is an unfortunate fact that making documentation longer can be an impediment -to understanding and can result in even more ways to misread or misinterpret the -text. Long descriptions full of corner cases and caveats can create the -impression that a function is more complex or harder to use than it actually is. - -Security Considerations (and Other Concerns) --------------------------------------------- - -Some modules provided with Python are inherently exposed to security issues -(e.g. shell injection vulnerabilities) due to the purpose of the module -(e.g. :mod:`ssl`). Littering the documentation of these modules with red -warning boxes for problems that are due to the task at hand, rather than -specifically to Python's support for that task, doesn't make for a good -reading experience. - -Instead, these security concerns should be gathered into a dedicated -"Security Considerations" section within the module's documentation, and -cross-referenced from the documentation of affected interfaces with a note -similar to ``"Please refer to the :ref:`security-considerations` section -for important information on how to avoid common mistakes."``. - -Similarly, if there is a common error that affects many interfaces in a -module (e.g. OS level pipe buffers filling up and stalling child processes), -these can be documented in a "Common Errors" section and cross-referenced -rather than repeated for every affected interface. - -Code Examples -------------- - -Short code examples can be a useful adjunct to understanding. Readers can often -grasp a simple example more quickly than they can digest a formal description in -prose. - -People learn faster with concrete, motivating examples that match the context of -a typical use case. For instance, the :meth:`str.rpartition` method is better -demonstrated with an example splitting the domain from a URL than it would be -with an example of removing the last word from a line of Monty Python dialog. - -The ellipsis for the :py:data:`sys.ps2` secondary interpreter prompt should only -be used sparingly, where it is necessary to clearly differentiate between input -lines and output lines. Besides contributing visual clutter, it makes it -difficult for readers to cut-and-paste examples so they can experiment with -variations. - -Code Equivalents ----------------- - -Giving pure Python code equivalents (or approximate equivalents) can be a useful -adjunct to a prose description. A documenter should carefully weigh whether the -code equivalent adds value. - -A good example is the code equivalent for :func:`all`. The short 4-line code -equivalent is easily digested; it re-emphasizes the early-out behavior; and it -clarifies the handling of the corner-case where the iterable is empty. In -addition, it serves as a model for people wanting to implement a commonly -requested alternative where :func:`all` would return the specific object -evaluating to False whenever the function terminates early. - -A more questionable example is the code for :func:`itertools.groupby`. Its code -equivalent borders on being too complex to be a quick aid to understanding. -Despite its complexity, the code equivalent was kept because it serves as a -model to alternative implementations and because the operation of the "grouper" -is more easily shown in code than in English prose. - -An example of when not to use a code equivalent is for the :func:`oct` function. -The exact steps in converting a number to octal doesn't add value for a user -trying to learn what the function does. - -Audience --------- - -The tone of the tutorial (and all the docs) needs to be respectful of the -reader's intelligence. Don't presume that the readers are stupid. Lay out the -relevant information, show motivating use cases, provide glossary links, and do -your best to connect-the-dots, but don't talk down to them or waste their time. - -The tutorial is meant for newcomers, many of whom will be using the tutorial to -evaluate the language as a whole. The experience needs to be positive and not -leave the reader with worries that something bad will happen if they make a -misstep. The tutorial serves as guide for intelligent and curious readers, -saving details for the how-to guides and other sources. - -Be careful accepting requests for documentation changes from the rare but vocal -category of reader who is looking for vindication for one of their programming -errors ("I made a mistake, therefore the docs must be wrong ..."). Typically, -the documentation wasn't consulted until after the error was made. It is -unfortunate, but typically no documentation edit would have saved the user from -making false assumptions about the language ("I was surprised by ..."). - .. _rst-primer: @@ -1832,7 +1614,6 @@ files in the root of the repository using the ``gettext_compact=0`` style. - .. _docutils: https://docutils.sourceforge.io/ .. _python-docs-theme: https://pypi.org/project/python-docs-theme/ .. _Sphinx: https://www.sphinx-doc.org/ @@ -1840,3 +1621,9 @@ style. .. _blurb: https://pypi.org/project/blurb/ .. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter .. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ + + +Style Guide +=========== + +Moved to :doc:`style-guide` diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst new file mode 100644 index 0000000000..366d6b23f6 --- /dev/null +++ b/documentation/style-guide.rst @@ -0,0 +1,220 @@ +.. _style-guide: + +=========== +Style Guide +=========== + +.. highlight:: rest + +Use of whitespace +================= + +All reST files use an indentation of 3 spaces; no tabs are allowed. The +maximum line length is 80 characters for normal text, but tables, deeply +indented code samples and long links may extend beyond that. Code example +bodies should use normal Python 4-space indentation. + +Make generous use of blank lines where applicable; they help group things +together. + +A sentence-ending period may be followed by one or two spaces; while reST +ignores the second space, it is customarily put in by some users, for example +to aid Emacs' auto-fill mode. + +Footnotes +========= + +Footnotes are generally discouraged, though they may be used when they are the +best way to present specific information. When a footnote reference is added at +the end of the sentence, it should follow the sentence-ending punctuation. The +reST markup should appear something like this:: + + This sentence has a footnote reference. [#]_ This is the next sentence. + +Footnotes should be gathered at the end of a file, or if the file is very long, +at the end of a section. The docutils will automatically create backlinks to +the footnote reference. + +Footnotes may appear in the middle of sentences where appropriate. + +Capitalization +============== + +.. sidebar:: Sentence case + + Sentence case is a set of capitalization rules used in English + sentences: the first word is always capitalized and other words are + only capitalized if there is a specific rule requiring it. + +In the Python documentation, the use of sentence case in section titles is +preferable, but consistency within a unit is more important than +following this rule. If you add a section to a chapter where most +sections are in title case, you can either convert all titles to +sentence case or use the dominant style in the new section title. + +Sentences that start with a word for which specific rules require +starting it with a lower case letter should be avoided. + +.. note:: + + Sections that describe a library module often have titles in the + form of "modulename --- Short description of the module." In this + case, the description should be capitalized as a stand-alone + sentence. + +Many special names are used in the Python documentation, including the names of +operating systems, programming languages, standards bodies, and the like. Most +of these entities are not assigned any special markup, but the preferred +spellings are given here to aid authors in maintaining the consistency of +presentation in the Python documentation. + +Other terms and words deserve special mention as well; these conventions should +be used to ensure consistency throughout the documentation: + +CPU + For "central processing unit." Many style guides say this should be + spelled out on the first use (and if you must use it, do so!). For + the Python documentation, this abbreviation should be avoided since + there's no reasonable way to predict which occurrence will be the + first seen by the reader. It is better to use the word "processor" + instead. + +POSIX + The name assigned to a particular group of standards. This is always + uppercase. + +Python + The name of our favorite programming language is always capitalized. + +reST + For "reStructuredText," an easy to read, plaintext markup syntax + used to produce Python documentation. When spelled out, it is + always one word and both forms start with a lower case 'r'. + +Unicode + The name of a character coding system. This is always written + capitalized. + +Unix + The name of the operating system developed at AT&T Bell Labs in the early + 1970s. + +Affirmative Tone +================ + +The documentation focuses on affirmatively stating what the language does and +how to use it effectively. + +Except for certain security or segfault risks, the docs should avoid +wording along the lines of "feature x is dangerous" or "experts only". These +kinds of value judgments belong in external blogs and wikis, not in the core +documentation. + +Bad example (creating worry in the mind of a reader): + + Warning: failing to explicitly close a file could result in lost data or + excessive resource consumption. Never rely on reference counting to + automatically close a file. + +Good example (establishing confident knowledge in the effective use of the +language): + + A best practice for using files is use a try/finally pair to explicitly + close a file after it is used. Alternatively, using a with-statement can + achieve the same effect. This assures that files are flushed and file + descriptor resources are released in a timely manner. + +Economy of Expression +===================== + +More documentation is not necessarily better documentation. Err on the side +of being succinct. + +It is an unfortunate fact that making documentation longer can be an impediment +to understanding and can result in even more ways to misread or misinterpret the +text. Long descriptions full of corner cases and caveats can create the +impression that a function is more complex or harder to use than it actually is. + +Security Considerations (and Other Concerns) +============================================ + +Some modules provided with Python are inherently exposed to security issues +(e.g. shell injection vulnerabilities) due to the purpose of the module +(e.g. :mod:`ssl`). Littering the documentation of these modules with red +warning boxes for problems that are due to the task at hand, rather than +specifically to Python's support for that task, doesn't make for a good +reading experience. + +Instead, these security concerns should be gathered into a dedicated +"Security Considerations" section within the module's documentation, and +cross-referenced from the documentation of affected interfaces with a note +similar to ``"Please refer to the :ref:`security-considerations` section +for important information on how to avoid common mistakes."``. + +Similarly, if there is a common error that affects many interfaces in a +module (e.g. OS level pipe buffers filling up and stalling child processes), +these can be documented in a "Common Errors" section and cross-referenced +rather than repeated for every affected interface. + +Code Examples +============= + +Short code examples can be a useful adjunct to understanding. Readers can often +grasp a simple example more quickly than they can digest a formal description in +prose. + +People learn faster with concrete, motivating examples that match the context of +a typical use case. For instance, the :meth:`str.rpartition` method is better +demonstrated with an example splitting the domain from a URL than it would be +with an example of removing the last word from a line of Monty Python dialog. + +The ellipsis for the :py:data:`sys.ps2` secondary interpreter prompt should only +be used sparingly, where it is necessary to clearly differentiate between input +lines and output lines. Besides contributing visual clutter, it makes it +difficult for readers to cut-and-paste examples so they can experiment with +variations. + +Code Equivalents +================ + +Giving pure Python code equivalents (or approximate equivalents) can be a useful +adjunct to a prose description. A documenter should carefully weigh whether the +code equivalent adds value. + +A good example is the code equivalent for :func:`all`. The short 4-line code +equivalent is easily digested; it re-emphasizes the early-out behavior; and it +clarifies the handling of the corner-case where the iterable is empty. In +addition, it serves as a model for people wanting to implement a commonly +requested alternative where :func:`all` would return the specific object +evaluating to False whenever the function terminates early. + +A more questionable example is the code for :func:`itertools.groupby`. Its code +equivalent borders on being too complex to be a quick aid to understanding. +Despite its complexity, the code equivalent was kept because it serves as a +model to alternative implementations and because the operation of the "grouper" +is more easily shown in code than in English prose. + +An example of when not to use a code equivalent is for the :func:`oct` function. +The exact steps in converting a number to octal doesn't add value for a user +trying to learn what the function does. + +Audience +======== + +The tone of the tutorial (and all the docs) needs to be respectful of the +reader's intelligence. Don't presume that the readers are stupid. Lay out the +relevant information, show motivating use cases, provide glossary links, and do +your best to connect-the-dots, but don't talk down to them or waste their time. + +The tutorial is meant for newcomers, many of whom will be using the tutorial to +evaluate the language as a whole. The experience needs to be positive and not +leave the reader with worries that something bad will happen if they make a +misstep. The tutorial serves as guide for intelligent and curious readers, +saving details for the how-to guides and other sources. + +Be careful accepting requests for documentation changes from the rare but vocal +category of reader who is looking for vindication for one of their programming +errors ("I made a mistake, therefore the docs must be wrong ..."). Typically, +the documentation wasn't consulted until after the error was made. It is +unfortunate, but typically no documentation edit would have saved the user from +making false assumptions about the language ("I was surprised by ..."). From 773b1c89c50db375415889210a91d2154e228502 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:41:01 +0100 Subject: [PATCH 12/21] Split out markup --- documentation/index.rst | 1 + documentation/markup.rst | 1238 +++++++++++++++++++++++++++ documentation/start-documenting.rst | 1231 -------------------------- 3 files changed, 1239 insertions(+), 1231 deletions(-) create mode 100644 documentation/markup.rst diff --git a/documentation/index.rst b/documentation/index.rst index be441935a2..4350178f89 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -8,3 +8,4 @@ Documentation start-documenting help-documenting style-guide + markup diff --git a/documentation/markup.rst b/documentation/markup.rst new file mode 100644 index 0000000000..3b08462eac --- /dev/null +++ b/documentation/markup.rst @@ -0,0 +1,1238 @@ +.. _markup: + +======================= +reStructuredText Markup +======================= + +.. highlight:: rest + + +.. _rst-primer: + +reStructuredText Primer +======================= + +This section is a brief introduction to reStructuredText (reST) concepts and +syntax, intended to provide authors with enough information to author documents +productively. Since reST was designed to be a simple, unobtrusive markup +language, this will not take too long. + +.. seealso:: + + The authoritative `reStructuredText User + Documentation `_. + + +Paragraphs +---------- + +The paragraph is the most basic block in a reST document. Paragraphs are simply +chunks of text separated by one or more blank lines. As in Python, indentation +is significant in reST, so all lines of the same paragraph must be left-aligned +to the same level of indentation. + + +Inline markup +------------- + +The standard reST inline markup is quite simple: use + +* one asterisk: ``*text*`` for emphasis (italics), +* two asterisks: ``**text**`` for strong emphasis (boldface), and +* backquotes: ````text```` for code samples. + +If asterisks or backquotes appear in running text and could be confused with +inline markup delimiters, they have to be escaped with a backslash. + +Be aware of some restrictions of this markup: + +* it may not be nested, +* content may not start or end with whitespace: ``* text*`` is wrong, +* it must be separated from surrounding text by non-word characters. Use a + backslash escaped space to work around that: ``thisis\ *one*\ word``. + +These restrictions may be lifted in future versions of the docutils. + +reST also allows for custom "interpreted text roles"', which signify that the +enclosed text should be interpreted in a specific way. Sphinx uses this to +provide semantic markup and cross-referencing of identifiers, as described in +the appropriate section. The general syntax is ``:rolename:`content```. + + +Lists and Quotes +---------------- + +List markup is natural: just place an asterisk at the start of a paragraph and +indent properly. The same goes for numbered lists; they can also be +automatically numbered using a ``#`` sign:: + + * This is a bulleted list. + * It has two items, the second + item uses two lines. + + 1. This is a numbered list. + 2. It has two items too. + + #. This is a numbered list. + #. It has two items too. + + +Nested lists are possible, but be aware that they must be separated from the +parent list items by blank lines:: + + * this is + * a list + + * with a nested list + * and some subitems + + * and here the parent list continues + +Definition lists are created as follows:: + + term (up to a line of text) + Definition of the term, which must be indented + + and can even consist of multiple paragraphs + + next term + Description. + + +Paragraphs are quoted by just indenting them more than the surrounding +paragraphs. + + +Source Code +----------- + +Literal code blocks are introduced by ending a paragraph with the special marker +``::``. The literal block must be indented:: + + This is a normal text paragraph. The next paragraph is a code sample:: + + It is not processed in any way, except + that the indentation is removed. + + It can span multiple lines. + + This is a normal text paragraph again. + +The handling of the ``::`` marker is smart: + +* If it occurs as a paragraph of its own, that paragraph is completely left + out of the document. +* If it is preceded by whitespace, the marker is removed. +* If it is preceded by non-whitespace, the marker is replaced by a single + colon. + +That way, the second sentence in the above example's first paragraph would be +rendered as "The next paragraph is a code sample:". + + +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`. + + +Sections +-------- + +Section headers are created by underlining (and optionally overlining) the +section title with a punctuation character, at least as long as the text:: + + ================= + This is a heading + ================= + +Normally, there are no heading levels assigned to certain characters as the +structure is determined from the succession of headings. However, for the +Python documentation, here is a suggested convention: + +* ``#`` with overline, for parts +* ``*`` with overline, for chapters +* ``=``, for sections +* ``-``, for subsections +* ``^``, for subsubsections +* ``"``, for paragraphs + + +Explicit Markup +--------------- + +"Explicit markup" is used in reST for most constructs that need special +handling, such as footnotes, specially-highlighted paragraphs, comments, and +generic directives. + +An explicit markup block begins with a line starting with ``..`` followed by +whitespace and is terminated by the next paragraph at the same level of +indentation. (There needs to be a blank line between explicit markup and normal +paragraphs. This may all sound a bit complicated, but it is intuitive enough +when you write it.) + + +Directives +---------- + +A directive is a generic block of explicit markup. Besides roles, it is one of +the extension mechanisms of reST, and Sphinx makes heavy use of it. + +Basically, a directive consists of a name, arguments, options and content. (Keep +this terminology in mind, it is used in the next chapter describing custom +directives.) Looking at this example, + +:: + + .. function:: foo(x) + foo(y, z) + :bar: no + + Return a line of text input from the user. + +``function`` is the directive name. It is given two arguments here, the +remainder of the first line and the second line, as well as one option ``bar`` +(as you can see, options are given in the lines immediately following the +arguments and indicated by the colons). + +The directive content follows after a blank line and is indented relative to the +directive start. + + +Footnotes +--------- + +For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote +body at the bottom of the document after a "Footnotes" rubric heading, like so:: + + Lorem ipsum [#]_ dolor sit amet ... [#]_ + + .. rubric:: Footnotes + + .. [#] Text of the first footnote. + .. [#] Text of the second footnote. + +You can also explicitly number the footnotes for better context. + + +Comments +-------- + +Every explicit markup block which isn't a valid markup construct (like the +footnotes above) is regarded as a comment. + + +Source encoding +--------------- + +Since the easiest way to include special characters like em dashes or copyright +signs in reST is to directly write them as Unicode characters, one has to +specify an encoding: + +All Python documentation source files must be in UTF-8 encoding, and the HTML +documents written from them will be in that encoding as well. + + +Gotchas +------- + +There are some problems one commonly runs into while authoring reST documents: + +* **Separation of inline markup:** As said above, inline markup spans must be + separated from the surrounding text by non-word characters, you have to use + an escaped space to get around that. + + +Additional Markup Constructs +============================ + +Sphinx adds a lot of new directives and interpreted text roles to standard reST +markup. This section contains the reference material for these facilities. +Documentation for "standard" reST constructs is not included here, though +they are used in the Python documentation. + +.. note:: + + This is just an overview of Sphinx' extended markup capabilities; full + coverage can be found in `its own documentation + `_. + + +Meta-information markup +----------------------- + +.. describe:: sectionauthor + + Identifies the author of the current section. The argument should include + the author's name such that it can be used for presentation (though it isn't) + and email address. The domain name portion of the address should be lower + case. Example:: + + .. sectionauthor:: Guido van Rossum + + Currently, this markup isn't reflected in the output in any way, but it helps + keep track of contributions. + + +Module-specific markup +---------------------- + +The markup described in this section is used to provide information about a +module being documented. Each module should be documented in its own file. +Normally this markup appears after the title heading of that file; a typical +file might start like this:: + + :mod:`parrot` -- Dead parrot access + =================================== + + .. module:: parrot + :platform: Unix, Windows + :synopsis: Analyze and reanimate dead parrots. + .. moduleauthor:: Eric Cleese + .. moduleauthor:: John Idle + +As you can see, the module-specific markup consists of two directives, the +``module`` directive and the ``moduleauthor`` directive. + +.. describe:: module + + This directive marks the beginning of the description of a module, package, + or submodule. The name should be fully qualified (i.e. including the + package name for submodules). + + The ``platform`` option, if present, is a comma-separated list of the + platforms on which the module is available (if it is available on all + platforms, the option should be omitted). The keys are short identifiers; + examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is + important to use a key which has already been used when applicable. + + The ``synopsis`` option should consist of one sentence describing the + module's purpose -- it is currently only used in the Global Module Index. + + The ``deprecated`` option can be given (with no value) to mark a module as + deprecated; it will be designated as such in various locations then. + +.. describe:: moduleauthor + + The ``moduleauthor`` directive, which can appear multiple times, names the + authors of the module code, just like ``sectionauthor`` names the author(s) + of a piece of documentation. It too does not result in any output currently. + +.. note:: + + It is important to make the section title of a module-describing file + meaningful since that value will be inserted in the table-of-contents trees + in overview files. + + +Information units +----------------- + +There are a number of directives used to describe specific features provided by +modules. Each directive requires one or more signatures to provide basic +information about what is being described, and the content should be the +description. The basic version makes entries in the general index; if no index +entry is desired, you can give the directive option flag ``:noindex:``. The +following example shows all of the features of this directive type:: + + .. function:: spam(eggs) + ham(eggs) + :noindex: + + Spam or ham the foo. + +The signatures of object methods or data attributes should not include the +class name, but be nested in a class directive. The generated files will +reflect this nesting, and the target identifiers (for HTML output) will use +both the class and method name, to enable consistent cross-references. If you +describe methods belonging to an abstract protocol such as context managers, +use a class directive with a (pseudo-)type name too to make the +index entries more informative. + +The directives are: + +.. describe:: c:function + + Describes a C function. The signature should be given as in C, e.g.:: + + .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + This is also used to describe function-like preprocessor macros. The names + of the arguments should be given so they may be used in the description. + + Note that you don't have to backslash-escape asterisks in the signature, + as it is not parsed by the reST inliner. + +.. describe:: c:member + + Describes a C struct member. Example signature:: + + .. c:member:: PyObject* PyTypeObject.tp_bases + + The text of the description should include the range of values allowed, how + the value should be interpreted, and whether the value can be changed. + References to structure members in text should use the ``member`` role. + +.. describe:: c:macro + + Describes a "simple" C macro. Simple macros are macros which are used + for code expansion, but which do not take arguments so cannot be described as + functions. This is not to be used for simple constant definitions. Examples + of its use in the Python documentation include :c:macro:`PyObject_HEAD` and + :c:macro:`Py_BEGIN_ALLOW_THREADS`. + +.. describe:: c:type + + Describes a C type. The signature should just be the type name. + +.. describe:: c:var + + Describes a global C variable. The signature should include the type, such + as:: + + .. c:var:: PyObject* PyClass_Type + +.. describe:: data + + Describes global data in a module, including both variables and values used + as "defined constants." Class and object attributes are not documented + using this directive. + +.. describe:: exception + + Describes an exception class. The signature can, but need not include + parentheses with constructor arguments. + +.. describe:: function + + Describes a module-level function. The signature should include the + parameters, enclosing optional parameters in brackets. Default values can be + given if it enhances clarity. For example:: + + .. function:: repeat([repeat=3[, number=1000000]]) + + Object methods are not documented using this directive. Bound object methods + placed in the module namespace as part of the public interface of the module + are documented using this, as they are equivalent to normal functions for + most purposes. + + The description should include information about the parameters required and + how they are used (especially whether mutable objects passed as parameters + are modified), side effects, and possible exceptions. A small example may be + provided. + +.. describe:: coroutinefunction + + Describes a module-level coroutine. The description should include similar + information to that described for ``function``. + +.. describe:: decorator + + Describes a decorator function. The signature should *not* represent the + signature of the actual function, but the usage as a decorator. For example, + given the functions + + .. code-block:: python + + def removename(func): + func.__name__ = '' + return func + + def setnewname(name): + def decorator(func): + func.__name__ = name + return func + return decorator + + the descriptions should look like this:: + + .. decorator:: removename + + Remove name of the decorated function. + + .. decorator:: setnewname(name) + + Set name of the decorated function to *name*. + + There is no ``deco`` role to link to a decorator that is marked up with + this directive; rather, use the ``:func:`` role. + +.. describe:: class + + Describes a class. The signature can include parentheses with parameters + which will be shown as the constructor arguments. + +.. describe:: attribute + + Describes an object data attribute. The description should include + information about the type of the data to be expected and whether it may be + changed directly. This directive should be nested in a class directive, + like in this example:: + + .. class:: Spam + + Description of the class. + + .. attribute:: ham + + Description of the attribute. + + If is also possible to document an attribute outside of a class directive, + for example if the documentation for different attributes and methods is + split in multiple sections. The class name should then be included + explicitly:: + + .. attribute:: Spam.eggs + +.. describe:: method + + Describes an object method. The parameters should not include the ``self`` + parameter. The description should include similar information to that + described for ``function``. This directive should be nested in a class + directive, like in the example above. + +.. describe:: coroutinemethod + + Describes an object coroutine method. The parameters should not include the + ``self`` parameter. The description should include similar information to + that described for ``function``. This directive should be nested in a + ``class`` directive. + +.. describe:: decoratormethod + + Same as ``decorator``, but for decorators that are methods. + + Refer to a decorator method using the ``:meth:`` role. + +.. describe:: staticmethod + + Describes an object static method. The description should include similar + information to that described for ``function``. This directive should be + nested in a ``class`` directive. + +.. describe:: classmethod + + Describes an object class method. The parameters should not include the + ``cls`` parameter. The description should include similar information to + that described for ``function``. This directive should be nested in a + ``class`` directive. + +.. describe:: abstractmethod + + Describes an object abstract method. The description should include similar + information to that described for ``function``. This directive should be + nested in a ``class`` directive. + +.. describe:: opcode + + Describes a Python :term:`bytecode` instruction. + +.. describe:: cmdoption + + Describes a Python command line option or switch. Option argument names + should be enclosed in angle brackets. Example:: + + .. cmdoption:: -m + + Run a module as a script. + +.. describe:: envvar + + Describes an environment variable that Python uses or defines. + + +There is also a generic version of these directives: + +.. describe:: describe + + This directive produces the same formatting as the specific ones explained + above but does not create index entries or cross-referencing targets. It is + used, for example, to describe the directives in this document. Example:: + + .. describe:: opcode + + Describes a Python bytecode instruction. + + +Showing code examples +--------------------- + +Examples of Python source code or interactive sessions are represented using +standard reST literal blocks. They are started by a ``::`` at the end of the +preceding paragraph and delimited by indentation. + +Representing an interactive session requires including the prompts and output +along with the Python code. No special markup is required for interactive +sessions. After the last line of input or output presented, there should not be +an "unused" primary prompt; this is an example of what *not* to do: + +.. code-block:: python + + >>> 1 + 1 + 2 + >>> + +Syntax highlighting is handled in a smart way: + +* There is a "highlighting language" for each source file. By default, + this is ``'python'`` as the majority of files will have to highlight Python + snippets. + +* Within Python highlighting mode, interactive sessions are recognized + automatically and highlighted appropriately. + +* The highlighting language can be changed using the ``highlight`` + directive, used as follows:: + + .. highlight:: c + + This language is used until the next ``highlight`` directive is + encountered. + +* The ``code-block`` directive can be used to specify the highlight language + of a single code block, e.g.:: + + .. code-block:: c + + #include + + void main() { + printf("Hello world!\n"); + } + +* The values normally used for the highlighting language are: + + * ``python`` (the default) + * ``c`` + * ``rest`` + * ``none`` (no highlighting) + +* If highlighting with the current language fails, the block is not highlighted + in any way. + +Longer displays of verbatim text may be included by storing the example text in +an external file containing only plain text. The file may be included using the +``literalinclude`` directive. [1]_ For example, to include the Python source +file :file:`example.py`, use:: + + .. literalinclude:: example.py + +The file name is relative to the current file's path. Documentation-specific +include files should be placed in the ``Doc/includes`` subdirectory. + +.. _rest-inline-markup: + +Inline markup +------------- + +As said before, Sphinx uses interpreted text roles to insert semantic markup in +documents. + +Names of local variables, such as function/method arguments, are an exception, +they should be marked simply with ``*var*``. + +For all other roles, you have to write ``:rolename:`content```. + +There are some additional facilities that make cross-referencing roles more +versatile: + +* You may supply an explicit title and reference target, like in reST direct + hyperlinks: ``:role:`title ``` will refer to *target*, but the link + text will be *title*. + +* If you prefix the content with ``!``, no reference/hyperlink will be created. + +* For the Python object roles, if you prefix the content with ``~``, the link + text will only be the last component of the target. For example, + ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only + display ``get`` as the link text. + + In HTML output, the link's ``title`` attribute (that is e.g. shown as a + tool-tip on mouse-hover) will always be the full target name. + +The following roles refer to objects in modules and are possibly hyperlinked if +a matching identifier is found: + +.. describe:: mod + + The name of a module; a dotted name may be used. This should also be used + for package names. + +.. describe:: func + + The name of a Python function; dotted names may be used. The role text + should not include trailing parentheses to enhance readability. The + parentheses are stripped when searching for identifiers. + +.. describe:: data + + The name of a module-level variable or constant. + +.. describe:: const + + The name of a "defined" constant. This may be a C-language ``#define`` + or a Python variable that is not intended to be changed. + +.. describe:: class + + A class name; a dotted name may be used. + +.. describe:: meth + + The name of a method of an object. The role text should include the type + name and the method name. A dotted name may be used. + +.. describe:: attr + + The name of a data attribute of an object. + +.. describe:: exc + + The name of an exception. A dotted name may be used. + +The name enclosed in this markup can include a module name and/or a class name. +For example, ``:func:`filter``` could refer to a function named ``filter`` in +the current module, or the built-in function of that name. In contrast, +``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` +module. + +Normally, names in these roles are searched first without any further +qualification, then with the current module name prepended, then with the +current module and class name (if any) prepended. If you prefix the name with a +dot, this order is reversed. For example, in the documentation of the +:mod:`codecs` module, ``:func:`open``` always refers to the built-in function, +while ``:func:`.open``` refers to :func:`codecs.open`. + +A similar heuristic is used to determine whether the name is an attribute of +the currently documented class. + +--------- + +The following roles create cross-references to C-language constructs if they +are defined in the API documentation: + +.. describe:: c:data + + The name of a C-language variable. + +.. describe:: c:func + + The name of a C-language function. Should include trailing parentheses. + +.. describe:: c:macro + + The name of a "simple" C macro, as defined above. + +.. describe:: c:type + + The name of a C-language type. + +.. describe:: c:member + + The name of a C type member, as defined above. + +--------- + +The following roles do not refer to objects, but can create cross-references or +internal links: + +.. describe:: envvar + + An environment variable. Index entries are generated. + +.. describe:: keyword + + The name of a Python keyword. Using this role will generate a link to the + documentation of the keyword. ``True``, ``False`` and ``None`` do not use + this role, but simple code markup (````True````), given that they're + fundamental to the language and should be known to any programmer. + +.. describe:: option + + A command-line option of Python. The leading hyphen(s) must be included. + If a matching ``cmdoption`` directive exists, it is linked to. For options + of other programs or scripts, use simple ````code```` markup. + +.. describe:: token + + The name of a grammar token (used in the reference manual to create links + between production displays). + +--------- + +The following role creates a cross-reference to the term in the glossary: + +.. describe:: term + + Reference to a term in the glossary. The glossary is created using the + ``glossary`` directive containing a definition list with terms and + definitions. It does not have to be in the same file as the ``term`` + markup, in fact, by default the Python docs have one global glossary + in the ``glossary.rst`` file. + + If you use a term that's not explained in a glossary, you'll get a warning + during build. + +--------- + +The following roles don't do anything special except formatting the text +in a different style: + +.. describe:: command + + The name of an OS-level command, such as ``rm``. + +.. describe:: dfn + + Mark the defining instance of a term in the text. (No index entries are + generated.) + +.. describe:: file + + The name of a file or directory. Within the contents, you can use curly + braces to indicate a "variable" part, for example:: + + ``spam`` is installed in :file:`/usr/lib/python2.{x}/site-packages` ... + + In the built documentation, the ``x`` will be displayed differently to + indicate that it is to be replaced by the Python minor version. + +.. describe:: guilabel + + Labels presented as part of an interactive user interface should be marked + using ``guilabel``. This includes labels from text-based interfaces such as + those created using :mod:`curses` or other text-based libraries. Any label + used in the interface should be marked with this role, including button + labels, window titles, field names, menu and menu selection names, and even + values in selection lists. + +.. describe:: kbd + + Mark a sequence of keystrokes. What form the key sequence takes may depend + on platform- or application-specific conventions. When there are no relevant + conventions, the names of modifier keys should be spelled out, to improve + accessibility for new users and non-native speakers. For example, an + *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without + reference to a specific application or platform, the same sequence should be + marked as ``:kbd:`Control-x Control-f```. + +.. describe:: mailheader + + The name of an RFC 822-style mail header. This markup does not imply that + the header is being used in an email message, but can be used to refer to any + header of the same "style." This is also used for headers defined by the + various MIME specifications. The header name should be entered in the same + way it would normally be found in practice, with the camel-casing conventions + being preferred where there is more than one common usage. For example: + ``:mailheader:`Content-Type```. + +.. describe:: makevar + + The name of a :command:`make` variable. + +.. describe:: manpage + + A reference to a Unix manual page including the section, + e.g. ``:manpage:`ls(1)```. + +.. describe:: menuselection + + Menu selections should be marked using the ``menuselection`` role. This is + used to mark a complete sequence of menu selections, including selecting + submenus and choosing a specific operation, or any subsequence of such a + sequence. The names of individual selections should be separated by + ``-->``. + + For example, to mark the selection "Start > Programs", use this markup:: + + :menuselection:`Start --> Programs` + + When including a selection that includes some trailing indicator, such as the + ellipsis some operating systems use to indicate that the command opens a + dialog, the indicator should be omitted from the selection name. + +.. describe:: mimetype + + The name of a MIME type, or a component of a MIME type (the major or minor + portion, taken alone). + +.. describe:: newsgroup + + The name of a Usenet newsgroup. + +.. describe:: program + + The name of an executable program. This may differ from the file name for + the executable for some platforms. In particular, the ``.exe`` (or other) + extension should be omitted for Windows programs. + +.. describe:: regexp + + A regular expression. Quotes should not be included. + +.. describe:: samp + + A piece of literal text, such as code. Within the contents, you can use + curly braces to indicate a "variable" part, as in ``:file:``. + + If you don't need the "variable part" indication, use the standard + ````code```` instead. + + +The following roles generate external links: + +.. describe:: pep + + A reference to a Python Enhancement Proposal. This generates appropriate + index entries. The text "PEP *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified PEP. Such + hyperlinks should not be a substitute for properly documenting the + language in the manuals. + +.. describe:: rfc + + A reference to an Internet Request for Comments. This generates appropriate + index entries. The text "RFC *number*\ " is generated; in the HTML output, + this text is a hyperlink to an online copy of the specified RFC. + + +Note that there are no special roles for including hyperlinks as you can use +the standard reST markup for that purpose. + + +.. _doc-ref-role: + +Cross-linking markup +-------------------- + +To support cross-referencing to arbitrary sections in the documentation, the +standard reST labels are "abused" a bit: Every label must precede a section +title; and every label name must be unique throughout the entire documentation +source. + +You can then reference to these sections using the ``:ref:`label-name``` role. + +Example:: + + .. _my-reference-label: + + Section to cross-reference + -------------------------- + + This is the text of the section. + + It refers to the section itself, see :ref:`my-reference-label`. + +The ``:ref:`` invocation is replaced with the section title. + +Alternatively, you can reference any label (not just section titles) +if you provide the link text ``:ref:`link text ```. + +Paragraph-level markup +---------------------- + +These directives create short paragraphs and can be used inside information +units as well as normal text: + +.. describe:: note + + An especially important bit of information about an API that a user should be + aware of when using whatever bit of API the note pertains to. The content of + the directive should be written in complete sentences and include all + appropriate punctuation. + + Example:: + + .. note:: + + This function is not suitable for sending spam e-mails. + +.. describe:: warning + + An important bit of information about an API that a user should be aware of + when using whatever bit of API the warning pertains to. The content of the + directive should be written in complete sentences and include all appropriate + punctuation. In the interest of not scaring users away from pages filled + with warnings, this directive should only be chosen over ``note`` for + information regarding the possibility of crashes, data loss, or security + implications. + +.. describe:: versionadded + + This directive documents the version of Python which added the described + feature, or a part of it, to the library or C API. When this applies to an + entire module, it should be placed at the top of the module section before + any prose. + + The first argument must be given and is the version in question. The second + argument is optional and can be used to describe the details of the feature. + + Example:: + + .. versionadded:: 3.5 + +.. describe:: versionchanged + + Similar to ``versionadded``, but describes when and what changed in the named + feature in some way (new parameters, changed side effects, platform support, + etc.). This one *must* have the second argument (explanation of the change). + + Example:: + + .. versionchanged:: 3.1 + The *spam* parameter was added. + + Note that there should be no blank line between the directive head and the + explanation; this is to make these blocks visually continuous in the markup. + +.. describe:: deprecated + + Indicates the version from which the described feature is deprecated. + + There is one required argument: the version from which the feature is + deprecated. + + Example:: + + .. deprecated:: 3.8 + +.. describe:: deprecated-removed + + Like ``deprecated``, but it also indicates in which version the feature is + removed. + + There are two required arguments: the version from which the feature is + deprecated, and the version in which the feature is removed. + + Example:: + + .. deprecated-removed:: 3.8 4.0 + +.. describe:: impl-detail + + This directive is used to mark CPython-specific information. Use either with + a block content or a single sentence as an argument, i.e. either :: + + .. impl-detail:: + + This describes some implementation detail. + + More explanation. + + or :: + + .. impl-detail:: This shortly mentions an implementation detail. + + "\ **CPython implementation detail:**\ " is automatically prepended to the + content. + +.. describe:: seealso + + Many sections include a list of references to module documentation or + external documents. These lists are created using the ``seealso`` directive. + + The ``seealso`` directive is typically placed in a section just before any + sub-sections. For the HTML output, it is shown boxed off from the main flow + of the text. + + The content of the ``seealso`` directive should be a reST definition list. + Example:: + + .. seealso:: + + Module :mod:`zipfile` + Documentation of the :mod:`zipfile` standard module. + + `GNU tar manual, Basic Tar Format `_ + Documentation for tar archive files, including GNU tar extensions. + +.. describe:: rubric + + This directive creates a paragraph heading that is not used to create a + table of contents node. It is currently used for the "Footnotes" caption. + +.. describe:: centered + + This directive creates a centered boldfaced paragraph. Use it as follows:: + + .. centered:: + + Paragraph contents. + + +Table-of-contents markup +------------------------ + +Since reST does not have facilities to interconnect several documents, or split +documents into multiple output files, Sphinx uses a custom directive to add +relations between the single files the documentation is made of, as well as +tables of contents. The ``toctree`` directive is the central element. + +.. describe:: toctree + + This directive inserts a "TOC tree" at the current location, using the + individual TOCs (including "sub-TOC trees") of the files given in the + directive body. A numeric ``maxdepth`` option may be given to indicate the + depth of the tree; by default, all levels are included. + + Consider this example (taken from the library reference index):: + + .. toctree:: + :maxdepth: 2 + + intro + strings + datatypes + numeric + (many more files listed here) + + This accomplishes two things: + + * Tables of contents from all those files are inserted, with a maximum depth + of two, that means one nested heading. ``toctree`` directives in those + files are also taken into account. + * Sphinx knows that the relative order of the files ``intro``, + ``strings`` and so forth, and it knows that they are children of the + shown file, the library index. From this information it generates "next + chapter", "previous chapter" and "parent chapter" links. + + In the end, all files included in the build process must occur in one + ``toctree`` directive; Sphinx will emit a warning if it finds a file that is + not included, because that means that this file will not be reachable through + standard navigation. + + The special file ``contents.rst`` at the root of the source directory is the + "root" of the TOC tree hierarchy; from it the "Contents" page is generated. + + +Index-generating markup +----------------------- + +Sphinx automatically creates index entries from all information units (like +functions, classes or attributes) like discussed before. + +However, there is also an explicit directive available, to make the index more +comprehensive and enable index entries in documents where information is not +mainly contained in information units, such as the language reference. + +The directive is ``index`` and contains one or more index entries. Each entry +consists of a type and a value, separated by a colon. + +For example:: + + .. index:: + single: execution; context + module: __main__ + module: sys + triple: module; search; path + +This directive contains five entries, which will be converted to entries in the +generated index which link to the exact location of the index statement (or, in +case of offline media, the corresponding page number). + +The possible entry types are: + +single + Creates a single index entry. Can be made a subentry by separating the + subentry text with a semicolon (this notation is also used below to describe + what entries are created). +pair + ``pair: loop; statement`` is a shortcut that creates two index entries, + namely ``loop; statement`` and ``statement; loop``. +triple + Likewise, ``triple: module; search; path`` is a shortcut that creates three + index entries, which are ``module; search path``, ``search; path, module`` + and ``path; module search``. +module, keyword, operator, object, exception, statement, builtin + These all create two index entries. For example, ``module: hashlib`` + creates the entries ``module; hashlib`` and ``hashlib; module``. The + builtin entry type is slightly different in that "built-in function" is used + in place of "builtin" when creating the two entries. + +For index directives containing only "single" entries, there is a shorthand +notation:: + + .. index:: BNF, grammar, syntax, notation + +This creates four index entries. + + +Grammar production displays +--------------------------- + +Special markup is available for displaying the productions of a formal grammar. +The markup is simple and does not attempt to model all aspects of BNF (or any +derived forms), but provides enough to allow context-free grammars to be +displayed in a way that causes uses of a symbol to be rendered as hyperlinks to +the definition of the symbol. There is this directive: + +.. describe:: productionlist + + This directive is used to enclose a group of productions. Each production is + given on a single line and consists of a name, separated by a colon from the + following definition. If the definition spans multiple lines, each + continuation line must begin with a colon placed at the same column as in the + first line. + + Blank lines are not allowed within ``productionlist`` directive arguments. + + The definition can contain token names which are marked as interpreted text + (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references + to the productions of these tokens. + + Note that no further reST parsing is done in the production, so that you + don't have to escape ``*`` or ``|`` characters. + + +.. XXX describe optional first parameter + +The following is an example taken from the Python Reference Manual:: + + .. productionlist:: + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` + + +Substitutions +------------- + +The documentation system provides three substitutions that are defined by +default. They are set in the build configuration file :file:`conf.py`. + +.. describe:: |release| + + Replaced by the Python release the documentation refers to. This is the full + version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``. + +.. describe:: |version| + + Replaced by the Python version the documentation refers to. This consists + only of the major and minor version parts, e.g. ``2.5``, even for version + 2.5.1. + +.. describe:: |today| + + Replaced by either today's date, or the date set in the build configuration + file. Normally has the format ``April 14, 2007``. + + +.. rubric:: Footnotes + +.. [1] There is a standard ``include`` directive, but it raises errors if the + file is not found. This one only emits a warning. diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 39a4eb4adf..a37b202fda 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -60,1237 +60,6 @@ Please don't let the material in this document stand between the documentation and your desire to help out! -.. _rst-primer: - -reStructuredText Primer -======================= - -This section is a brief introduction to reStructuredText (reST) concepts and -syntax, intended to provide authors with enough information to author documents -productively. Since reST was designed to be a simple, unobtrusive markup -language, this will not take too long. - -.. seealso:: - - The authoritative `reStructuredText User - Documentation `_. - - -Paragraphs ----------- - -The paragraph is the most basic block in a reST document. Paragraphs are simply -chunks of text separated by one or more blank lines. As in Python, indentation -is significant in reST, so all lines of the same paragraph must be left-aligned -to the same level of indentation. - - -Inline markup -------------- - -The standard reST inline markup is quite simple: use - -* one asterisk: ``*text*`` for emphasis (italics), -* two asterisks: ``**text**`` for strong emphasis (boldface), and -* backquotes: ````text```` for code samples. - -If asterisks or backquotes appear in running text and could be confused with -inline markup delimiters, they have to be escaped with a backslash. - -Be aware of some restrictions of this markup: - -* it may not be nested, -* content may not start or end with whitespace: ``* text*`` is wrong, -* it must be separated from surrounding text by non-word characters. Use a - backslash escaped space to work around that: ``thisis\ *one*\ word``. - -These restrictions may be lifted in future versions of the docutils. - -reST also allows for custom "interpreted text roles"', which signify that the -enclosed text should be interpreted in a specific way. Sphinx uses this to -provide semantic markup and cross-referencing of identifiers, as described in -the appropriate section. The general syntax is ``:rolename:`content```. - - -Lists and Quotes ----------------- - -List markup is natural: just place an asterisk at the start of a paragraph and -indent properly. The same goes for numbered lists; they can also be -automatically numbered using a ``#`` sign:: - - * This is a bulleted list. - * It has two items, the second - item uses two lines. - - 1. This is a numbered list. - 2. It has two items too. - - #. This is a numbered list. - #. It has two items too. - - -Nested lists are possible, but be aware that they must be separated from the -parent list items by blank lines:: - - * this is - * a list - - * with a nested list - * and some subitems - - * and here the parent list continues - -Definition lists are created as follows:: - - term (up to a line of text) - Definition of the term, which must be indented - - and can even consist of multiple paragraphs - - next term - Description. - - -Paragraphs are quoted by just indenting them more than the surrounding -paragraphs. - - -Source Code ------------ - -Literal code blocks are introduced by ending a paragraph with the special marker -``::``. The literal block must be indented:: - - This is a normal text paragraph. The next paragraph is a code sample:: - - It is not processed in any way, except - that the indentation is removed. - - It can span multiple lines. - - This is a normal text paragraph again. - -The handling of the ``::`` marker is smart: - -* If it occurs as a paragraph of its own, that paragraph is completely left - out of the document. -* If it is preceded by whitespace, the marker is removed. -* If it is preceded by non-whitespace, the marker is replaced by a single - colon. - -That way, the second sentence in the above example's first paragraph would be -rendered as "The next paragraph is a code sample:". - - -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`. - - -Sections --------- - -Section headers are created by underlining (and optionally overlining) the -section title with a punctuation character, at least as long as the text:: - - ================= - This is a heading - ================= - -Normally, there are no heading levels assigned to certain characters as the -structure is determined from the succession of headings. However, for the -Python documentation, here is a suggested convention: - -* ``#`` with overline, for parts -* ``*`` with overline, for chapters -* ``=``, for sections -* ``-``, for subsections -* ``^``, for subsubsections -* ``"``, for paragraphs - - -Explicit Markup ---------------- - -"Explicit markup" is used in reST for most constructs that need special -handling, such as footnotes, specially-highlighted paragraphs, comments, and -generic directives. - -An explicit markup block begins with a line starting with ``..`` followed by -whitespace and is terminated by the next paragraph at the same level of -indentation. (There needs to be a blank line between explicit markup and normal -paragraphs. This may all sound a bit complicated, but it is intuitive enough -when you write it.) - - -Directives ----------- - -A directive is a generic block of explicit markup. Besides roles, it is one of -the extension mechanisms of reST, and Sphinx makes heavy use of it. - -Basically, a directive consists of a name, arguments, options and content. (Keep -this terminology in mind, it is used in the next chapter describing custom -directives.) Looking at this example, - -:: - - .. function:: foo(x) - foo(y, z) - :bar: no - - Return a line of text input from the user. - -``function`` is the directive name. It is given two arguments here, the -remainder of the first line and the second line, as well as one option ``bar`` -(as you can see, options are given in the lines immediately following the -arguments and indicated by the colons). - -The directive content follows after a blank line and is indented relative to the -directive start. - - -Footnotes ---------- - -For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote -body at the bottom of the document after a "Footnotes" rubric heading, like so:: - - Lorem ipsum [#]_ dolor sit amet ... [#]_ - - .. rubric:: Footnotes - - .. [#] Text of the first footnote. - .. [#] Text of the second footnote. - -You can also explicitly number the footnotes for better context. - - -Comments --------- - -Every explicit markup block which isn't a valid markup construct (like the -footnotes above) is regarded as a comment. - - -Source encoding ---------------- - -Since the easiest way to include special characters like em dashes or copyright -signs in reST is to directly write them as Unicode characters, one has to -specify an encoding: - -All Python documentation source files must be in UTF-8 encoding, and the HTML -documents written from them will be in that encoding as well. - - -Gotchas -------- - -There are some problems one commonly runs into while authoring reST documents: - -* **Separation of inline markup:** As said above, inline markup spans must be - separated from the surrounding text by non-word characters, you have to use - an escaped space to get around that. - - -Additional Markup Constructs -============================ - -Sphinx adds a lot of new directives and interpreted text roles to standard reST -markup. This section contains the reference material for these facilities. -Documentation for "standard" reST constructs is not included here, though -they are used in the Python documentation. - -.. note:: - - This is just an overview of Sphinx' extended markup capabilities; full - coverage can be found in `its own documentation - `_. - - -Meta-information markup ------------------------ - -.. describe:: sectionauthor - - Identifies the author of the current section. The argument should include - the author's name such that it can be used for presentation (though it isn't) - and email address. The domain name portion of the address should be lower - case. Example:: - - .. sectionauthor:: Guido van Rossum - - Currently, this markup isn't reflected in the output in any way, but it helps - keep track of contributions. - - -Module-specific markup ----------------------- - -The markup described in this section is used to provide information about a -module being documented. Each module should be documented in its own file. -Normally this markup appears after the title heading of that file; a typical -file might start like this:: - - :mod:`parrot` -- Dead parrot access - =================================== - - .. module:: parrot - :platform: Unix, Windows - :synopsis: Analyze and reanimate dead parrots. - .. moduleauthor:: Eric Cleese - .. moduleauthor:: John Idle - -As you can see, the module-specific markup consists of two directives, the -``module`` directive and the ``moduleauthor`` directive. - -.. describe:: module - - This directive marks the beginning of the description of a module, package, - or submodule. The name should be fully qualified (i.e. including the - package name for submodules). - - The ``platform`` option, if present, is a comma-separated list of the - platforms on which the module is available (if it is available on all - platforms, the option should be omitted). The keys are short identifiers; - examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is - important to use a key which has already been used when applicable. - - The ``synopsis`` option should consist of one sentence describing the - module's purpose -- it is currently only used in the Global Module Index. - - The ``deprecated`` option can be given (with no value) to mark a module as - deprecated; it will be designated as such in various locations then. - -.. describe:: moduleauthor - - The ``moduleauthor`` directive, which can appear multiple times, names the - authors of the module code, just like ``sectionauthor`` names the author(s) - of a piece of documentation. It too does not result in any output currently. - -.. note:: - - It is important to make the section title of a module-describing file - meaningful since that value will be inserted in the table-of-contents trees - in overview files. - - -Information units ------------------ - -There are a number of directives used to describe specific features provided by -modules. Each directive requires one or more signatures to provide basic -information about what is being described, and the content should be the -description. The basic version makes entries in the general index; if no index -entry is desired, you can give the directive option flag ``:noindex:``. The -following example shows all of the features of this directive type:: - - .. function:: spam(eggs) - ham(eggs) - :noindex: - - Spam or ham the foo. - -The signatures of object methods or data attributes should not include the -class name, but be nested in a class directive. The generated files will -reflect this nesting, and the target identifiers (for HTML output) will use -both the class and method name, to enable consistent cross-references. If you -describe methods belonging to an abstract protocol such as context managers, -use a class directive with a (pseudo-)type name too to make the -index entries more informative. - -The directives are: - -.. describe:: c:function - - Describes a C function. The signature should be given as in C, e.g.:: - - .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) - - This is also used to describe function-like preprocessor macros. The names - of the arguments should be given so they may be used in the description. - - Note that you don't have to backslash-escape asterisks in the signature, - as it is not parsed by the reST inliner. - -.. describe:: c:member - - Describes a C struct member. Example signature:: - - .. c:member:: PyObject* PyTypeObject.tp_bases - - The text of the description should include the range of values allowed, how - the value should be interpreted, and whether the value can be changed. - References to structure members in text should use the ``member`` role. - -.. describe:: c:macro - - Describes a "simple" C macro. Simple macros are macros which are used - for code expansion, but which do not take arguments so cannot be described as - functions. This is not to be used for simple constant definitions. Examples - of its use in the Python documentation include :c:macro:`PyObject_HEAD` and - :c:macro:`Py_BEGIN_ALLOW_THREADS`. - -.. describe:: c:type - - Describes a C type. The signature should just be the type name. - -.. describe:: c:var - - Describes a global C variable. The signature should include the type, such - as:: - - .. c:var:: PyObject* PyClass_Type - -.. describe:: data - - Describes global data in a module, including both variables and values used - as "defined constants." Class and object attributes are not documented - using this directive. - -.. describe:: exception - - Describes an exception class. The signature can, but need not include - parentheses with constructor arguments. - -.. describe:: function - - Describes a module-level function. The signature should include the - parameters, enclosing optional parameters in brackets. Default values can be - given if it enhances clarity. For example:: - - .. function:: repeat([repeat=3[, number=1000000]]) - - Object methods are not documented using this directive. Bound object methods - placed in the module namespace as part of the public interface of the module - are documented using this, as they are equivalent to normal functions for - most purposes. - - The description should include information about the parameters required and - how they are used (especially whether mutable objects passed as parameters - are modified), side effects, and possible exceptions. A small example may be - provided. - -.. describe:: coroutinefunction - - Describes a module-level coroutine. The description should include similar - information to that described for ``function``. - -.. describe:: decorator - - Describes a decorator function. The signature should *not* represent the - signature of the actual function, but the usage as a decorator. For example, - given the functions - - .. code-block:: python - - def removename(func): - func.__name__ = '' - return func - - def setnewname(name): - def decorator(func): - func.__name__ = name - return func - return decorator - - the descriptions should look like this:: - - .. decorator:: removename - - Remove name of the decorated function. - - .. decorator:: setnewname(name) - - Set name of the decorated function to *name*. - - There is no ``deco`` role to link to a decorator that is marked up with - this directive; rather, use the ``:func:`` role. - -.. describe:: class - - Describes a class. The signature can include parentheses with parameters - which will be shown as the constructor arguments. - -.. describe:: attribute - - Describes an object data attribute. The description should include - information about the type of the data to be expected and whether it may be - changed directly. This directive should be nested in a class directive, - like in this example:: - - .. class:: Spam - - Description of the class. - - .. attribute:: ham - - Description of the attribute. - - If is also possible to document an attribute outside of a class directive, - for example if the documentation for different attributes and methods is - split in multiple sections. The class name should then be included - explicitly:: - - .. attribute:: Spam.eggs - -.. describe:: method - - Describes an object method. The parameters should not include the ``self`` - parameter. The description should include similar information to that - described for ``function``. This directive should be nested in a class - directive, like in the example above. - -.. describe:: coroutinemethod - - Describes an object coroutine method. The parameters should not include the - ``self`` parameter. The description should include similar information to - that described for ``function``. This directive should be nested in a - ``class`` directive. - -.. describe:: decoratormethod - - Same as ``decorator``, but for decorators that are methods. - - Refer to a decorator method using the ``:meth:`` role. - -.. describe:: staticmethod - - Describes an object static method. The description should include similar - information to that described for ``function``. This directive should be - nested in a ``class`` directive. - -.. describe:: classmethod - - Describes an object class method. The parameters should not include the - ``cls`` parameter. The description should include similar information to - that described for ``function``. This directive should be nested in a - ``class`` directive. - -.. describe:: abstractmethod - - Describes an object abstract method. The description should include similar - information to that described for ``function``. This directive should be - nested in a ``class`` directive. - -.. describe:: opcode - - Describes a Python :term:`bytecode` instruction. - -.. describe:: cmdoption - - Describes a Python command line option or switch. Option argument names - should be enclosed in angle brackets. Example:: - - .. cmdoption:: -m - - Run a module as a script. - -.. describe:: envvar - - Describes an environment variable that Python uses or defines. - - -There is also a generic version of these directives: - -.. describe:: describe - - This directive produces the same formatting as the specific ones explained - above but does not create index entries or cross-referencing targets. It is - used, for example, to describe the directives in this document. Example:: - - .. describe:: opcode - - Describes a Python bytecode instruction. - - -Showing code examples ---------------------- - -Examples of Python source code or interactive sessions are represented using -standard reST literal blocks. They are started by a ``::`` at the end of the -preceding paragraph and delimited by indentation. - -Representing an interactive session requires including the prompts and output -along with the Python code. No special markup is required for interactive -sessions. After the last line of input or output presented, there should not be -an "unused" primary prompt; this is an example of what *not* to do: - -.. code-block:: python - - >>> 1 + 1 - 2 - >>> - -Syntax highlighting is handled in a smart way: - -* There is a "highlighting language" for each source file. By default, - this is ``'python'`` as the majority of files will have to highlight Python - snippets. - -* Within Python highlighting mode, interactive sessions are recognized - automatically and highlighted appropriately. - -* The highlighting language can be changed using the ``highlight`` - directive, used as follows:: - - .. highlight:: c - - This language is used until the next ``highlight`` directive is - encountered. - -* The ``code-block`` directive can be used to specify the highlight language - of a single code block, e.g.:: - - .. code-block:: c - - #include - - void main() { - printf("Hello world!\n"); - } - -* The values normally used for the highlighting language are: - - * ``python`` (the default) - * ``c`` - * ``rest`` - * ``none`` (no highlighting) - -* If highlighting with the current language fails, the block is not highlighted - in any way. - -Longer displays of verbatim text may be included by storing the example text in -an external file containing only plain text. The file may be included using the -``literalinclude`` directive. [1]_ For example, to include the Python source -file :file:`example.py`, use:: - - .. literalinclude:: example.py - -The file name is relative to the current file's path. Documentation-specific -include files should be placed in the ``Doc/includes`` subdirectory. - -.. _rest-inline-markup: - -Inline markup -------------- - -As said before, Sphinx uses interpreted text roles to insert semantic markup in -documents. - -Names of local variables, such as function/method arguments, are an exception, -they should be marked simply with ``*var*``. - -For all other roles, you have to write ``:rolename:`content```. - -There are some additional facilities that make cross-referencing roles more -versatile: - -* You may supply an explicit title and reference target, like in reST direct - hyperlinks: ``:role:`title ``` will refer to *target*, but the link - text will be *title*. - -* If you prefix the content with ``!``, no reference/hyperlink will be created. - -* For the Python object roles, if you prefix the content with ``~``, the link - text will only be the last component of the target. For example, - ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only - display ``get`` as the link text. - - In HTML output, the link's ``title`` attribute (that is e.g. shown as a - tool-tip on mouse-hover) will always be the full target name. - -The following roles refer to objects in modules and are possibly hyperlinked if -a matching identifier is found: - -.. describe:: mod - - The name of a module; a dotted name may be used. This should also be used - for package names. - -.. describe:: func - - The name of a Python function; dotted names may be used. The role text - should not include trailing parentheses to enhance readability. The - parentheses are stripped when searching for identifiers. - -.. describe:: data - - The name of a module-level variable or constant. - -.. describe:: const - - The name of a "defined" constant. This may be a C-language ``#define`` - or a Python variable that is not intended to be changed. - -.. describe:: class - - A class name; a dotted name may be used. - -.. describe:: meth - - The name of a method of an object. The role text should include the type - name and the method name. A dotted name may be used. - -.. describe:: attr - - The name of a data attribute of an object. - -.. describe:: exc - - The name of an exception. A dotted name may be used. - -The name enclosed in this markup can include a module name and/or a class name. -For example, ``:func:`filter``` could refer to a function named ``filter`` in -the current module, or the built-in function of that name. In contrast, -``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` -module. - -Normally, names in these roles are searched first without any further -qualification, then with the current module name prepended, then with the -current module and class name (if any) prepended. If you prefix the name with a -dot, this order is reversed. For example, in the documentation of the -:mod:`codecs` module, ``:func:`open``` always refers to the built-in function, -while ``:func:`.open``` refers to :func:`codecs.open`. - -A similar heuristic is used to determine whether the name is an attribute of -the currently documented class. - ---------- - -The following roles create cross-references to C-language constructs if they -are defined in the API documentation: - -.. describe:: c:data - - The name of a C-language variable. - -.. describe:: c:func - - The name of a C-language function. Should include trailing parentheses. - -.. describe:: c:macro - - The name of a "simple" C macro, as defined above. - -.. describe:: c:type - - The name of a C-language type. - -.. describe:: c:member - - The name of a C type member, as defined above. - ---------- - -The following roles do not refer to objects, but can create cross-references or -internal links: - -.. describe:: envvar - - An environment variable. Index entries are generated. - -.. describe:: keyword - - The name of a Python keyword. Using this role will generate a link to the - documentation of the keyword. ``True``, ``False`` and ``None`` do not use - this role, but simple code markup (````True````), given that they're - fundamental to the language and should be known to any programmer. - -.. describe:: option - - A command-line option of Python. The leading hyphen(s) must be included. - If a matching ``cmdoption`` directive exists, it is linked to. For options - of other programs or scripts, use simple ````code```` markup. - -.. describe:: token - - The name of a grammar token (used in the reference manual to create links - between production displays). - ---------- - -The following role creates a cross-reference to the term in the glossary: - -.. describe:: term - - Reference to a term in the glossary. The glossary is created using the - ``glossary`` directive containing a definition list with terms and - definitions. It does not have to be in the same file as the ``term`` - markup, in fact, by default the Python docs have one global glossary - in the ``glossary.rst`` file. - - If you use a term that's not explained in a glossary, you'll get a warning - during build. - ---------- - -The following roles don't do anything special except formatting the text -in a different style: - -.. describe:: command - - The name of an OS-level command, such as ``rm``. - -.. describe:: dfn - - Mark the defining instance of a term in the text. (No index entries are - generated.) - -.. describe:: file - - The name of a file or directory. Within the contents, you can use curly - braces to indicate a "variable" part, for example:: - - ``spam`` is installed in :file:`/usr/lib/python2.{x}/site-packages` ... - - In the built documentation, the ``x`` will be displayed differently to - indicate that it is to be replaced by the Python minor version. - -.. describe:: guilabel - - Labels presented as part of an interactive user interface should be marked - using ``guilabel``. This includes labels from text-based interfaces such as - those created using :mod:`curses` or other text-based libraries. Any label - used in the interface should be marked with this role, including button - labels, window titles, field names, menu and menu selection names, and even - values in selection lists. - -.. describe:: kbd - - Mark a sequence of keystrokes. What form the key sequence takes may depend - on platform- or application-specific conventions. When there are no relevant - conventions, the names of modifier keys should be spelled out, to improve - accessibility for new users and non-native speakers. For example, an - *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without - reference to a specific application or platform, the same sequence should be - marked as ``:kbd:`Control-x Control-f```. - -.. describe:: mailheader - - The name of an RFC 822-style mail header. This markup does not imply that - the header is being used in an email message, but can be used to refer to any - header of the same "style." This is also used for headers defined by the - various MIME specifications. The header name should be entered in the same - way it would normally be found in practice, with the camel-casing conventions - being preferred where there is more than one common usage. For example: - ``:mailheader:`Content-Type```. - -.. describe:: makevar - - The name of a :command:`make` variable. - -.. describe:: manpage - - A reference to a Unix manual page including the section, - e.g. ``:manpage:`ls(1)```. - -.. describe:: menuselection - - Menu selections should be marked using the ``menuselection`` role. This is - used to mark a complete sequence of menu selections, including selecting - submenus and choosing a specific operation, or any subsequence of such a - sequence. The names of individual selections should be separated by - ``-->``. - - For example, to mark the selection "Start > Programs", use this markup:: - - :menuselection:`Start --> Programs` - - When including a selection that includes some trailing indicator, such as the - ellipsis some operating systems use to indicate that the command opens a - dialog, the indicator should be omitted from the selection name. - -.. describe:: mimetype - - The name of a MIME type, or a component of a MIME type (the major or minor - portion, taken alone). - -.. describe:: newsgroup - - The name of a Usenet newsgroup. - -.. describe:: program - - The name of an executable program. This may differ from the file name for - the executable for some platforms. In particular, the ``.exe`` (or other) - extension should be omitted for Windows programs. - -.. describe:: regexp - - A regular expression. Quotes should not be included. - -.. describe:: samp - - A piece of literal text, such as code. Within the contents, you can use - curly braces to indicate a "variable" part, as in ``:file:``. - - If you don't need the "variable part" indication, use the standard - ````code```` instead. - - -The following roles generate external links: - -.. describe:: pep - - A reference to a Python Enhancement Proposal. This generates appropriate - index entries. The text "PEP *number*\ " is generated; in the HTML output, - this text is a hyperlink to an online copy of the specified PEP. Such - hyperlinks should not be a substitute for properly documenting the - language in the manuals. - -.. describe:: rfc - - A reference to an Internet Request for Comments. This generates appropriate - index entries. The text "RFC *number*\ " is generated; in the HTML output, - this text is a hyperlink to an online copy of the specified RFC. - - -Note that there are no special roles for including hyperlinks as you can use -the standard reST markup for that purpose. - - -.. _doc-ref-role: - -Cross-linking markup --------------------- - -To support cross-referencing to arbitrary sections in the documentation, the -standard reST labels are "abused" a bit: Every label must precede a section -title; and every label name must be unique throughout the entire documentation -source. - -You can then reference to these sections using the ``:ref:`label-name``` role. - -Example:: - - .. _my-reference-label: - - Section to cross-reference - -------------------------- - - This is the text of the section. - - It refers to the section itself, see :ref:`my-reference-label`. - -The ``:ref:`` invocation is replaced with the section title. - -Alternatively, you can reference any label (not just section titles) -if you provide the link text ``:ref:`link text ```. - -Paragraph-level markup ----------------------- - -These directives create short paragraphs and can be used inside information -units as well as normal text: - -.. describe:: note - - An especially important bit of information about an API that a user should be - aware of when using whatever bit of API the note pertains to. The content of - the directive should be written in complete sentences and include all - appropriate punctuation. - - Example:: - - .. note:: - - This function is not suitable for sending spam e-mails. - -.. describe:: warning - - An important bit of information about an API that a user should be aware of - when using whatever bit of API the warning pertains to. The content of the - directive should be written in complete sentences and include all appropriate - punctuation. In the interest of not scaring users away from pages filled - with warnings, this directive should only be chosen over ``note`` for - information regarding the possibility of crashes, data loss, or security - implications. - -.. describe:: versionadded - - This directive documents the version of Python which added the described - feature, or a part of it, to the library or C API. When this applies to an - entire module, it should be placed at the top of the module section before - any prose. - - The first argument must be given and is the version in question. The second - argument is optional and can be used to describe the details of the feature. - - Example:: - - .. versionadded:: 3.5 - -.. describe:: versionchanged - - Similar to ``versionadded``, but describes when and what changed in the named - feature in some way (new parameters, changed side effects, platform support, - etc.). This one *must* have the second argument (explanation of the change). - - Example:: - - .. versionchanged:: 3.1 - The *spam* parameter was added. - - Note that there should be no blank line between the directive head and the - explanation; this is to make these blocks visually continuous in the markup. - -.. describe:: deprecated - - Indicates the version from which the described feature is deprecated. - - There is one required argument: the version from which the feature is - deprecated. - - Example:: - - .. deprecated:: 3.8 - -.. describe:: deprecated-removed - - Like ``deprecated``, but it also indicates in which version the feature is - removed. - - There are two required arguments: the version from which the feature is - deprecated, and the version in which the feature is removed. - - Example:: - - .. deprecated-removed:: 3.8 4.0 - -.. describe:: impl-detail - - This directive is used to mark CPython-specific information. Use either with - a block content or a single sentence as an argument, i.e. either :: - - .. impl-detail:: - - This describes some implementation detail. - - More explanation. - - or :: - - .. impl-detail:: This shortly mentions an implementation detail. - - "\ **CPython implementation detail:**\ " is automatically prepended to the - content. - -.. describe:: seealso - - Many sections include a list of references to module documentation or - external documents. These lists are created using the ``seealso`` directive. - - The ``seealso`` directive is typically placed in a section just before any - sub-sections. For the HTML output, it is shown boxed off from the main flow - of the text. - - The content of the ``seealso`` directive should be a reST definition list. - Example:: - - .. seealso:: - - Module :mod:`zipfile` - Documentation of the :mod:`zipfile` standard module. - - `GNU tar manual, Basic Tar Format `_ - Documentation for tar archive files, including GNU tar extensions. - -.. describe:: rubric - - This directive creates a paragraph heading that is not used to create a - table of contents node. It is currently used for the "Footnotes" caption. - -.. describe:: centered - - This directive creates a centered boldfaced paragraph. Use it as follows:: - - .. centered:: - - Paragraph contents. - - -Table-of-contents markup ------------------------- - -Since reST does not have facilities to interconnect several documents, or split -documents into multiple output files, Sphinx uses a custom directive to add -relations between the single files the documentation is made of, as well as -tables of contents. The ``toctree`` directive is the central element. - -.. describe:: toctree - - This directive inserts a "TOC tree" at the current location, using the - individual TOCs (including "sub-TOC trees") of the files given in the - directive body. A numeric ``maxdepth`` option may be given to indicate the - depth of the tree; by default, all levels are included. - - Consider this example (taken from the library reference index):: - - .. toctree:: - :maxdepth: 2 - - intro - strings - datatypes - numeric - (many more files listed here) - - This accomplishes two things: - - * Tables of contents from all those files are inserted, with a maximum depth - of two, that means one nested heading. ``toctree`` directives in those - files are also taken into account. - * Sphinx knows that the relative order of the files ``intro``, - ``strings`` and so forth, and it knows that they are children of the - shown file, the library index. From this information it generates "next - chapter", "previous chapter" and "parent chapter" links. - - In the end, all files included in the build process must occur in one - ``toctree`` directive; Sphinx will emit a warning if it finds a file that is - not included, because that means that this file will not be reachable through - standard navigation. - - The special file ``contents.rst`` at the root of the source directory is the - "root" of the TOC tree hierarchy; from it the "Contents" page is generated. - - -Index-generating markup ------------------------ - -Sphinx automatically creates index entries from all information units (like -functions, classes or attributes) like discussed before. - -However, there is also an explicit directive available, to make the index more -comprehensive and enable index entries in documents where information is not -mainly contained in information units, such as the language reference. - -The directive is ``index`` and contains one or more index entries. Each entry -consists of a type and a value, separated by a colon. - -For example:: - - .. index:: - single: execution; context - module: __main__ - module: sys - triple: module; search; path - -This directive contains five entries, which will be converted to entries in the -generated index which link to the exact location of the index statement (or, in -case of offline media, the corresponding page number). - -The possible entry types are: - -single - Creates a single index entry. Can be made a subentry by separating the - subentry text with a semicolon (this notation is also used below to describe - what entries are created). -pair - ``pair: loop; statement`` is a shortcut that creates two index entries, - namely ``loop; statement`` and ``statement; loop``. -triple - Likewise, ``triple: module; search; path`` is a shortcut that creates three - index entries, which are ``module; search path``, ``search; path, module`` - and ``path; module search``. -module, keyword, operator, object, exception, statement, builtin - These all create two index entries. For example, ``module: hashlib`` - creates the entries ``module; hashlib`` and ``hashlib; module``. The - builtin entry type is slightly different in that "built-in function" is used - in place of "builtin" when creating the two entries. - -For index directives containing only "single" entries, there is a shorthand -notation:: - - .. index:: BNF, grammar, syntax, notation - -This creates four index entries. - - -Grammar production displays ---------------------------- - -Special markup is available for displaying the productions of a formal grammar. -The markup is simple and does not attempt to model all aspects of BNF (or any -derived forms), but provides enough to allow context-free grammars to be -displayed in a way that causes uses of a symbol to be rendered as hyperlinks to -the definition of the symbol. There is this directive: - -.. describe:: productionlist - - This directive is used to enclose a group of productions. Each production is - given on a single line and consists of a name, separated by a colon from the - following definition. If the definition spans multiple lines, each - continuation line must begin with a colon placed at the same column as in the - first line. - - Blank lines are not allowed within ``productionlist`` directive arguments. - - The definition can contain token names which are marked as interpreted text - (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references - to the productions of these tokens. - - Note that no further reST parsing is done in the production, so that you - don't have to escape ``*`` or ``|`` characters. - - -.. XXX describe optional first parameter - -The following is an example taken from the Python Reference Manual:: - - .. productionlist:: - try_stmt: try1_stmt | try2_stmt - try1_stmt: "try" ":" `suite` - : ("except" [`expression` ["," `target`]] ":" `suite`)+ - : ["else" ":" `suite`] - : ["finally" ":" `suite`] - try2_stmt: "try" ":" `suite` - : "finally" ":" `suite` - - -Substitutions -------------- - -The documentation system provides three substitutions that are defined by -default. They are set in the build configuration file :file:`conf.py`. - -.. describe:: |release| - - Replaced by the Python release the documentation refers to. This is the full - version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``. - -.. describe:: |version| - - Replaced by the Python version the documentation refers to. This consists - only of the major and minor version parts, e.g. ``2.5``, even for version - 2.5.1. - -.. describe:: |today| - - Replaced by either today's date, or the date set in the build configuration - file. Normally has the format ``April 14, 2007``. - - -.. rubric:: Footnotes - -.. [1] There is a standard ``include`` directive, but it raises errors if the - file is not found. This one only emits a warning. - - .. _building-doc: Building the documentation From aa1194f2aab3a9440d8328d29370a9618c7cdf02 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:50:35 +0100 Subject: [PATCH 13/21] Split out translating --- documentation/index.rst | 1 + documentation/start-documenting.rst | 256 +--------------------------- documentation/translating.rst | 253 +++++++++++++++++++++++++++ 3 files changed, 260 insertions(+), 250 deletions(-) create mode 100644 documentation/translating.rst diff --git a/documentation/index.rst b/documentation/index.rst index 4350178f89..1c5558a744 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -9,3 +9,4 @@ Documentation help-documenting style-guide markup + translating diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index a37b202fda..6c9fcf38f3 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -134,265 +134,21 @@ Sphinx_, blurb_ and python-docs-theme_ packages from PyPI):: where ```` is one of html, text, latex, or htmlhelp (for explanations see the make targets above). -.. _translating: - -Translating -=========== - -Python documentation translations are governed by :PEP:`545`. -They are built by `docsbuild-scripts -`__ and hosted on -docs.python.org. There are several documentation translations already -in production; others are works in progress. - -+-----------------+-------------------------------+----------------------------+ -| Language | Contact | Links | -+=================+===============================+============================+ -| Arabic (ar) | `Abdur-Rahmaan Janhangeer | `GitHub `_ | -| | `_ | | -+-----------------+-------------------------------+----------------------------+ -| Bengali as | `Kushal Das `_ | `GitHub `_ | -| spoken in | | | -| India (bn_IN) | | | -+-----------------+-------------------------------+----------------------------+ -| French (fr) | `Julien Palard (@JulienPalard)| `GitHub `_ | -| | `_ | | -+-----------------+-------------------------------+----------------------------+ -| Hindi as spoken | | `GitHub `_ | -| in India (hi_IN)| | | -+-----------------+-------------------------------+----------------------------+ -| Hungarian (hu) | `Tamás Bajusz (@gbtami) | `GitHub `_ | -| | `_ | `Mailing List `_ | -+-----------------+-------------------------------+----------------------------+ -| Indonesian (id) | `Oon Arfiandwi `_ | `GitHub `_ | -+-----------------+-------------------------------+----------------------------+ -| Italian (it) | | `mail `_ | -+-----------------+-------------------------------+----------------------------+ -| Japanese (ja) | `Kinebuchi Tomohiko | `GitHub `_ | -| | (@cocoatomo) `_| `Doc `_ | -+-----------------+-------------------------------+----------------------------+ -| Korean (ko) | | `GitHub `_ | -| | | `Doc `_ | -+-----------------+-------------------------------+----------------------------+ -| Marathi (mr) | `Sanket Garade | `GitHub `_ | -| | `_ | | -+-----------------+-------------------------------+----------------------------+ -| Lithuanian (lt) | | `mail `_ | -+-----------------+-------------------------------+----------------------------+ -| Persian (fa) | `Komeil Parseh (@mmdbalkhi) | `GitHub `_ | -| | `_ | | -+-----------------+-------------------------------+----------------------------+ -| Polish (pl) | | `GitHub `_ | -| | | `Translations `_ | -| | | `Doc `_ | -| | | `mail `_ | -+-----------------+-------------------------------+----------------------------+ -| Portuguese (pt) | Gustavo Toffo | | -+-----------------+-------------------------------+----------------------------+ -| Portuguese | Marco Rougeth | `GitHub `_ | -| as spoken | | `Wiki `_ | -| in Brasil | | `Telegram `_ | -| (pt-br) | | `article `_| -+-----------------+-------------------------------+----------------------------+ -| Russian (ru) | | `mail `_ | -+-----------------+-------------------------------+----------------------------+ -| Simplified | `Shengjing Zhu `_ | `Transifex `_ | -| Chinese | | `GitHub `_ | -| (zh-cn) | | `Doc `_ | -+-----------------+-------------------------------+----------------------------+ -| Spanish (es) | Raúl Cumplido | `GitHub `_ | -+-----------------+-------------------------------+----------------------------+ -| Traditional | `王威翔 Matt Wang | `GitHub `_ | -| Chinese | `_, | `Doc `_ | -| (zh-tw) | Josix Wang | | -+-----------------+-------------------------------+----------------------------+ -| Turkish (tr) | `Ege Akman (@egeakman) | `GitHub `_ | -| | `_ | | -+-----------------+-------------------------------+----------------------------+ - -.. _article_pt_br: https://rgth.co/blog/python-ptbr-cenario-atual/ -.. _gh_cocoatomo: https://github.com/cocoatomo -.. _gh_gbtami: https://github.com/gbtami -.. _gh_kushal: https://github.com/Kushal997-das -.. _gh_mdk: https://github.com/JulienPalard -.. _gh_mmdbalkhi: https://github.com/mmdbalkhi -.. _gh_oonid: https://github.com/oonid -.. _gh_osdotsystem: https://github.com/Abdur-rahmaanJ -.. _gh_zhsj: https://github.com/zhsj -.. _gh_mattwang44: https://github.com/mattwang44 -.. _email_egeakman: mailto:egeakmanegeakman@hotmail.com -.. _email_garade: mailto:garade@pm.me -.. _chat_pt_br: https://t.me/pybr_i18n -.. _doc_ja: https://docs.python.org/ja/ -.. _doc_ko: https://docs.python.org/ko/ -.. _doc_pl: https://docs.python.org/pl/ -.. _doc_zh_cn: https://docs.python.org/zh-cn/ -.. _doc_zh_tw: https://docs.python.org/zh-tw/ -.. _github_ar: https://github.com/Abdur-rahmaanJ/python-docs-ar -.. _github_bn_in: https://github.com/python/python-docs-bn-in -.. _github_es: https://github.com/python/python-docs-es -.. _github_fa: https://github.com/mmdbalkhi/python-docs-fa -.. _github_fr: https://github.com/python/python-docs-fr -.. _github_hi_in: https://github.com/CuriousLearner/python-docs-hi-in -.. _github_hu: https://github.com/python/python-docs-hu -.. _github_id: https://github.com/python/python-docs-id -.. _github_ja: https://github.com/python/python-docs-ja -.. _github_ko: https://github.com/python/python-docs-ko -.. _github_mr: https://github.com/sanketgarade/python-doc-mr -.. _github_pl: https://github.com/python/python-docs-pl -.. _github_pt_br: https://github.com/python/python-docs-pt-br -.. _github_tr: https://github.com/python-docs-tr/python-docs-tr -.. _github_zh_cn: https://github.com/python/python-docs-zh-cn -.. _github_zh_tw: https://github.com/python/python-docs-zh-tw -.. _list_hu: https://mail.python.org/pipermail/python-hu -.. _mail_it: https://mail.python.org/pipermail/doc-sig/2019-April/004114.html -.. _mail_lt: https://mail.python.org/pipermail/doc-sig/2019-July/004138.html -.. _mail_pl: https://mail.python.org/pipermail/doc-sig/2019-April/004106.html -.. _mail_ru: https://mail.python.org/pipermail/doc-sig/2019-May/004131.html -.. _tx_pl: https://www.transifex.com/python-doc/python-newest/ -.. _tx_zh_cn: https://www.transifex.com/python-doc/python-newest/ -.. _wiki_pt_br: https://python.org.br/traducao/ - -Starting a new translation --------------------------- - -First subscribe to the `translation mailing list `_, -and introduce yourself and the translation you're starting. Translations -fall under the aegis of the `PSF Translation Workgroup `_ - -Then you can bootstrap your new translation by using our `cookiecutter -`__. - -The important steps look like this: - -- Create the GitHub repo (anywhere) with the right hierarchy (using the - cookiecutter). -- Gather people to help you translate. You can't do it alone. -- You can use any tool to translate, as long as you can synchronize with git. - Some use Transifex, and some use only GitHub. You can choose another - way if you like; it's up to you. -- Ensure we update this page to reflect your work and progress, either via a - PR or by asking on the `translation mailing list `_. -- When ``bugs.html``, ``tutorial``, and ``library/functions`` are 100% - completed, ask on the `translation mailing list `_ for - your language to be added in the language picker on docs.python.org. - - -PEP 545 summary: ----------------- - -Here are the essential points of :PEP:`545`: - -- Each translation is assigned an appropriate lowercased language tag, - with an optional region subtag, and joined with a dash, like - ``pt-br`` or ``fr``. - -- Each translation is under CC0 and marked as such in the README (as in - the cookiecutter). - -- Translation files are hosted on - ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not - mandatory to start a translation, but mandatory to land on - ``docs.python.org``). - -- Translations having completed ``tutorial/``, ``library/stdtypes`` - and ``library/functions`` are hosted on - ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. - - -How to get help ---------------- - -Discussions about translations occur on the `translation mailing list `_, -and there's a `Libera.Chat IRC `_ channel, -``#python-doc``. - - -Translation FAQ ---------------- - -Which version of the Python documentation should be translated? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Consensus is to work on current stable. You can then propagate your -translation from one branch to another using `pomerge -`__. - - -Are there some tools to help in managing the repo? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Here's what we're using: - -- `pomerge `__ to propagate translations - from one file to others. -- `pospell `__ to check for typos in ``.po`` files. -- `powrap `__ to rewrap the ``.po`` files - before committing. This helps keep git diffs short. -- `potodo `__ to list what needs to be translated. - - -How is a coordinator elected? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -There is no election; each translation has to sort this out. Here are some suggestions. - -- Coordinator requests are to be public on the `translation mailing list `_. -- If the given language has a native core dev, the core dev has their - say on the choice. -- Anyone who wants to become coordinator for their native language and shows - motivation by translating and building a community will be named - coordinator. -- In case of concurrency between two persons, no one will sort this out - for you. It is up to you two to organize a local election or whatever is - needed to sort this out. -- If a coordinator becomes inactive or unreachable for a long - period of time, someone else can ask for a takeover on the `translation mailing list `_. - - -The entry for my translation is missing/not up to date on this page -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Ask on the `translation mailing list `_, or better, make a PR on the `devguide -`__. - - -I have a translation, but it's not in git. What should I do? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can ask for help on the `translation mailing list `_, and -the team will help you create an appropriate repository. You can still use tools like transifex, -if you like. - - -My git hierarchy does not match yours. Can I keep it? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -No, inside the ``github.com/python`` organization we’ll all have the -exact same hierarchy so bots will be able to build all of our -translations. So you may have to convert from one hierarchy to another. -Ask for help on the `translation mailing list `_ if you’re -not sure on how to do it. - - -What hierarchy should I use in my GitHub repository? -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As for every project, we have a *branch* per version. We store ``.po`` -files in the root of the repository using the ``gettext_compact=0`` -style. - .. _docutils: https://docutils.sourceforge.io/ .. _python-docs-theme: https://pypi.org/project/python-docs-theme/ .. _Sphinx: https://www.sphinx-doc.org/ .. _virtualenv: https://virtualenv.pypa.io/ .. _blurb: https://pypi.org/project/blurb/ -.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter -.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ Style Guide =========== Moved to :doc:`style-guide` + + +Translating +=========== + +Moved to :doc:`translating` diff --git a/documentation/translating.rst b/documentation/translating.rst new file mode 100644 index 0000000000..fff7a53e4e --- /dev/null +++ b/documentation/translating.rst @@ -0,0 +1,253 @@ +.. _translating: + +=========== +Translating +=========== + +.. highlight:: rest + +Python documentation translations are governed by :PEP:`545`. +They are built by `docsbuild-scripts +`__ and hosted on +docs.python.org. There are several documentation translations already +in production; others are works in progress. + ++-----------------+-------------------------------+----------------------------+ +| Language | Contact | Links | ++=================+===============================+============================+ +| Arabic (ar) | `Abdur-Rahmaan Janhangeer | `GitHub `_ | +| | `_ | | ++-----------------+-------------------------------+----------------------------+ +| Bengali as | `Kushal Das `_ | `GitHub `_ | +| spoken in | | | +| India (bn_IN) | | | ++-----------------+-------------------------------+----------------------------+ +| French (fr) | `Julien Palard (@JulienPalard)| `GitHub `_ | +| | `_ | | ++-----------------+-------------------------------+----------------------------+ +| Hindi as spoken | | `GitHub `_ | +| in India (hi_IN)| | | ++-----------------+-------------------------------+----------------------------+ +| Hungarian (hu) | `Tamás Bajusz (@gbtami) | `GitHub `_ | +| | `_ | `Mailing List `_ | ++-----------------+-------------------------------+----------------------------+ +| Indonesian (id) | `Oon Arfiandwi `_ | `GitHub `_ | ++-----------------+-------------------------------+----------------------------+ +| Italian (it) | | `mail `_ | ++-----------------+-------------------------------+----------------------------+ +| Japanese (ja) | `Kinebuchi Tomohiko | `GitHub `_ | +| | (@cocoatomo) `_| `Doc `_ | ++-----------------+-------------------------------+----------------------------+ +| Korean (ko) | | `GitHub `_ | +| | | `Doc `_ | ++-----------------+-------------------------------+----------------------------+ +| Marathi (mr) | `Sanket Garade | `GitHub `_ | +| | `_ | | ++-----------------+-------------------------------+----------------------------+ +| Lithuanian (lt) | | `mail `_ | ++-----------------+-------------------------------+----------------------------+ +| Persian (fa) | `Komeil Parseh (@mmdbalkhi) | `GitHub `_ | +| | `_ | | ++-----------------+-------------------------------+----------------------------+ +| Polish (pl) | | `GitHub `_ | +| | | `Translations `_ | +| | | `Doc `_ | +| | | `mail `_ | ++-----------------+-------------------------------+----------------------------+ +| Portuguese (pt) | Gustavo Toffo | | ++-----------------+-------------------------------+----------------------------+ +| Portuguese | Marco Rougeth | `GitHub `_ | +| as spoken | | `Wiki `_ | +| in Brasil | | `Telegram `_ | +| (pt-br) | | `article `_| ++-----------------+-------------------------------+----------------------------+ +| Russian (ru) | | `mail `_ | ++-----------------+-------------------------------+----------------------------+ +| Simplified | `Shengjing Zhu `_ | `Transifex `_ | +| Chinese | | `GitHub `_ | +| (zh-cn) | | `Doc `_ | ++-----------------+-------------------------------+----------------------------+ +| Spanish (es) | Raúl Cumplido | `GitHub `_ | ++-----------------+-------------------------------+----------------------------+ +| Traditional | `王威翔 Matt Wang | `GitHub `_ | +| Chinese | `_, | `Doc `_ | +| (zh-tw) | Josix Wang | | ++-----------------+-------------------------------+----------------------------+ +| Turkish (tr) | `Ege Akman (@egeakman) | `GitHub `_ | +| | `_ | | ++-----------------+-------------------------------+----------------------------+ + +.. _article_pt_br: https://rgth.co/blog/python-ptbr-cenario-atual/ +.. _gh_cocoatomo: https://github.com/cocoatomo +.. _gh_gbtami: https://github.com/gbtami +.. _gh_kushal: https://github.com/Kushal997-das +.. _gh_mdk: https://github.com/JulienPalard +.. _gh_mmdbalkhi: https://github.com/mmdbalkhi +.. _gh_oonid: https://github.com/oonid +.. _gh_osdotsystem: https://github.com/Abdur-rahmaanJ +.. _gh_zhsj: https://github.com/zhsj +.. _gh_mattwang44: https://github.com/mattwang44 +.. _email_egeakman: mailto:egeakmanegeakman@hotmail.com +.. _email_garade: mailto:garade@pm.me +.. _chat_pt_br: https://t.me/pybr_i18n +.. _doc_ja: https://docs.python.org/ja/ +.. _doc_ko: https://docs.python.org/ko/ +.. _doc_pl: https://docs.python.org/pl/ +.. _doc_zh_cn: https://docs.python.org/zh-cn/ +.. _doc_zh_tw: https://docs.python.org/zh-tw/ +.. _github_ar: https://github.com/Abdur-rahmaanJ/python-docs-ar +.. _github_bn_in: https://github.com/python/python-docs-bn-in +.. _github_es: https://github.com/python/python-docs-es +.. _github_fa: https://github.com/mmdbalkhi/python-docs-fa +.. _github_fr: https://github.com/python/python-docs-fr +.. _github_hi_in: https://github.com/CuriousLearner/python-docs-hi-in +.. _github_hu: https://github.com/python/python-docs-hu +.. _github_id: https://github.com/python/python-docs-id +.. _github_ja: https://github.com/python/python-docs-ja +.. _github_ko: https://github.com/python/python-docs-ko +.. _github_mr: https://github.com/sanketgarade/python-doc-mr +.. _github_pl: https://github.com/python/python-docs-pl +.. _github_pt_br: https://github.com/python/python-docs-pt-br +.. _github_tr: https://github.com/python-docs-tr/python-docs-tr +.. _github_zh_cn: https://github.com/python/python-docs-zh-cn +.. _github_zh_tw: https://github.com/python/python-docs-zh-tw +.. _list_hu: https://mail.python.org/pipermail/python-hu +.. _mail_it: https://mail.python.org/pipermail/doc-sig/2019-April/004114.html +.. _mail_lt: https://mail.python.org/pipermail/doc-sig/2019-July/004138.html +.. _mail_pl: https://mail.python.org/pipermail/doc-sig/2019-April/004106.html +.. _mail_ru: https://mail.python.org/pipermail/doc-sig/2019-May/004131.html +.. _tx_pl: https://www.transifex.com/python-doc/python-newest/ +.. _tx_zh_cn: https://www.transifex.com/python-doc/python-newest/ +.. _wiki_pt_br: https://python.org.br/traducao/ + +Starting a new translation +========================== + +First subscribe to the `translation mailing list `_, +and introduce yourself and the translation you're starting. Translations +fall under the aegis of the `PSF Translation Workgroup `_ + +Then you can bootstrap your new translation by using our `cookiecutter +`__. + +The important steps look like this: + +- Create the GitHub repo (anywhere) with the right hierarchy (using the + cookiecutter). +- Gather people to help you translate. You can't do it alone. +- You can use any tool to translate, as long as you can synchronize with git. + Some use Transifex, and some use only GitHub. You can choose another + way if you like; it's up to you. +- Ensure we update this page to reflect your work and progress, either via a + PR or by asking on the `translation mailing list `_. +- When ``bugs.html``, ``tutorial``, and ``library/functions`` are 100% + completed, ask on the `translation mailing list `_ for + your language to be added in the language picker on docs.python.org. + + +PEP 545 summary +=============== + +Here are the essential points of :PEP:`545`: + +- Each translation is assigned an appropriate lowercased language tag, + with an optional region subtag, and joined with a dash, like + ``pt-br`` or ``fr``. + +- Each translation is under CC0 and marked as such in the README (as in + the cookiecutter). + +- Translation files are hosted on + ``https://github.com/python/python-docs-{LANGUAGE_TAG}`` (not + mandatory to start a translation, but mandatory to land on + ``docs.python.org``). + +- Translations having completed ``tutorial/``, ``library/stdtypes`` + and ``library/functions`` are hosted on + ``https://docs.python.org/{LANGUAGE_TAG}/{VERSION_TAG}/``. + + +How to get help +=============== + +Discussions about translations occur on the `translation mailing list `_, +and there's a `Libera.Chat IRC `_ channel, +``#python-doc``. + + +Translation FAQ +=============== + +Which version of the Python documentation should be translated? +--------------------------------------------------------------- + +Consensus is to work on current stable. You can then propagate your +translation from one branch to another using `pomerge +`__. + + +Are there some tools to help in managing the repo? +-------------------------------------------------- + +Here's what we're using: + +- `pomerge `__ to propagate translations + from one file to others. +- `pospell `__ to check for typos in ``.po`` files. +- `powrap `__ to rewrap the ``.po`` files + before committing. This helps keep git diffs short. +- `potodo `__ to list what needs to be translated. + + +How is a coordinator elected? +----------------------------- + +There is no election; each translation has to sort this out. Here are some suggestions. + +- Coordinator requests are to be public on the `translation mailing list `_. +- If the given language has a native core dev, the core dev has their + say on the choice. +- Anyone who wants to become coordinator for their native language and shows + motivation by translating and building a community will be named + coordinator. +- In case of concurrency between two persons, no one will sort this out + for you. It is up to you two to organize a local election or whatever is + needed to sort this out. +- If a coordinator becomes inactive or unreachable for a long + period of time, someone else can ask for a takeover on the `translation mailing list `_. + + +The entry for my translation is missing/not up to date on this page +------------------------------------------------------------------- + +Ask on the `translation mailing list `_, or better, make a PR on the `devguide +`__. + + +I have a translation, but it's not in git. What should I do? +------------------------------------------------------------ + +You can ask for help on the `translation mailing list `_, and +the team will help you create an appropriate repository. You can still use tools like transifex, +if you like. + + +My git hierarchy does not match yours. Can I keep it? +----------------------------------------------------- + +No, inside the ``github.com/python`` organization we’ll all have the +exact same hierarchy so bots will be able to build all of our +translations. So you may have to convert from one hierarchy to another. +Ask for help on the `translation mailing list `_ if you’re +not sure on how to do it. + + +What hierarchy should I use in my GitHub repository? +---------------------------------------------------- + +As for every project, we have a *branch* per version. We store ``.po`` +files in the root of the repository using the ``gettext_compact=0`` +style. + +.. _translation_wg: https://wiki.python.org/psf/TranslationWG/Charter +.. _translation_ml: https://mail.python.org/mailman3/lists/translation.python.org/ From 2305cbe3cd655ba177ddef4e2902e59bac7de1a6 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 20:58:49 +0100 Subject: [PATCH 14/21] Split out contributing to the devguide --- documentation/devguide.rst | 54 ++++++++++++++++++++++++++++++ documentation/help-documenting.rst | 54 ------------------------------ documentation/index.rst | 1 + index.rst | 4 +-- 4 files changed, 57 insertions(+), 56 deletions(-) create mode 100644 documentation/devguide.rst diff --git a/documentation/devguide.rst b/documentation/devguide.rst new file mode 100644 index 0000000000..fb69988561 --- /dev/null +++ b/documentation/devguide.rst @@ -0,0 +1,54 @@ +.. _devguide: + +================================== +Helping with the Developer's Guide +================================== + +.. highlight:: console + +The Developer's Guide (what you're reading now) uses the same process as the +main Python documentation, except for some small differences. The source +lives in a `separate repository`_ and bug reports should be submitted to the +`devguide GitHub tracker`_. + +Our devguide workflow uses continuous integration and deployment so changes to +the devguide are normally published when the pull request is merged. Changes +to CPython documentation follow the workflow of a CPython release and are +published in the release. + + +Developer's Guide workflow +========================== + +To submit a :ref:`pull request `, you can fork the +`devguide repo`_ to your GitHub account and clone it using:: + + $ git clone https://github.com//devguide + +For your PR to be accepted, you will also need to sign the +:ref:`contributor agreement `. + +To build the devguide, some additional dependencies are required (most +importantly, `Sphinx`_), and the standard way to install dependencies in +Python projects is to create a virtualenv, and then install dependencies from +a ``requirements.txt`` file. For your convenience, this is all *automated for +you*. To build the devguide on a Unix-like system use:: + + $ make html + +in the checkout directory. On Windows use: + +.. code-block:: doscon + + > .\make html + +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 :ref:`pull request `. You may wish to run ``make check`` +and ``make linkcheck`` to make sure that it runs without errors. + +.. _separate repository: +.. _devguide repo: https://github.com/python/devguide +.. _devguide GitHub tracker: https://github.com/python/devguide/issues +.. _Sphinx: https://www.sphinx-doc.org/ diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 60022d1f17..2a804990cc 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -82,58 +82,4 @@ a pull request directly. It's best to avoid filing a single issue for an entire section containing multiple problems; instead, file several issues so that it is easier to break the work up for multiple people and more efficient review. - -.. _helping-with-the-developers-guide: - -Helping with the Developer's Guide ----------------------------------- - -.. highlight:: console - -The Developer's Guide (what you're reading now) uses the same process as the -main Python documentation, except for some small differences. The source -lives in a `separate repository`_ and bug reports should be submitted to the -`devguide GitHub tracker`_. - -Our devguide workflow uses continuous integration and deployment so changes to -the devguide are normally published when the pull request is merged. Changes -to CPython documentation follow the workflow of a CPython release and are -published in the release. - - -Developer's Guide workflow --------------------------- - -To submit a :ref:`pull request `, you can fork the -`devguide repo`_ to your GitHub account and clone it using:: - - $ git clone https://github.com//devguide - -For your PR to be accepted, you will also need to sign the -:ref:`contributor agreement `. - -To build the devguide, some additional dependencies are required (most -importantly, `Sphinx`_), and the standard way to install dependencies in -Python projects is to create a virtualenv, and then install dependencies from -a ``requirements.txt`` file. For your convenience, this is all *automated for -you*. To build the devguide on a Unix-like system use:: - - $ make html - -in the checkout directory. On Windows use: - -.. code-block:: doscon - - > .\make html - -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 :ref:`pull request `. You may wish to run ``make check`` -and ``make linkcheck`` to make sure that it runs without errors. - -.. _separate repository: -.. _devguide repo: https://github.com/python/devguide -.. _devguide GitHub tracker: https://github.com/python/devguide/issues -.. _Sphinx: https://www.sphinx-doc.org/ .. _issue tracker: https://github.com/python/cpython/issues diff --git a/documentation/index.rst b/documentation/index.rst index 1c5558a744..3f2512bcfb 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -10,3 +10,4 @@ Documentation style-guide markup translating + devguide diff --git a/index.rst b/index.rst index c30de4798a..24d26bbe12 100644 --- a/index.rst +++ b/index.rst @@ -6,7 +6,7 @@ Python Developer's Guide This guide is a comprehensive resource for :ref:`contributing ` to Python_ -- for both new and experienced contributors. It is -:ref:`maintained ` by the same +:ref:`maintained ` by the same community that maintains Python. We welcome your contributions to Python! .. _quick-reference: @@ -259,7 +259,7 @@ Additional Resources -------------------- * Anyone can clone the sources for this guide. See - :ref:`helping-with-the-developers-guide`. + :ref:`devguide`. * Help with ... * :ref:`exploring` * :ref:`grammar` From 0329309ea7203910c072850f4869f48c7eafe857 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 21:03:16 +0100 Subject: [PATCH 15/21] Split out core dev process from responsibilities --- core-developers/become-core-developer.rst | 130 +--------------------- core-developers/index.rst | 1 + core-developers/responsibilities.rst | 122 ++++++++++++++++++++ 3 files changed, 128 insertions(+), 125 deletions(-) create mode 100644 core-developers/responsibilities.rst diff --git a/core-developers/become-core-developer.rst b/core-developers/become-core-developer.rst index d6b8a850e6..e5c862fb96 100644 --- a/core-developers/become-core-developer.rst +++ b/core-developers/become-core-developer.rst @@ -1,10 +1,11 @@ .. _coredev: -How to Become a Core Developer -============================== +================================ + How to Become a Core Developer +================================ What it Takes -------------- +============= When you have consistently contributed patches which meet quality standards without requiring extensive rewrites prior to being committed, @@ -19,47 +20,9 @@ developers agree that you should gain commit privileges you are then extended an official offer. How core developers come to that agreement are outlined in :pep:`13`. -What it Means -------------- - -As contributors to the CPython project, our shared responsibility is to -collaborate constructively with other contributors, including core developers. -This responsibility covers all forms of contribution, whether that's submitting -patches to the implementation or documentation, reviewing other peoples' -patches, triaging issues on the issue tracker, or discussing design and -development ideas on the core mailing lists. - -Core developers accept key additional responsibilities around the ongoing -management of the project: - -* core developers bear the additional responsibility of handling the - consequences of accepting a change into the code base or documentation. - That includes reverting or fixing it if it causes problems in the - Buildbot fleet or someone spots a problem in post-commit review, as well - as helping out the release manager in resolving any problems found during - the pre-release testing cycle. While all contributors are free to help out - with this part of the process, and it is most welcome when they do, the - actual responsibility rests with the core developer that merged the change -* core developers also bear the primary responsibility for deciding when - changes proposed on the issue tracker should be escalated to python-ideas - or python-dev for wider discussion, as well as suggesting the use of the - Python Enhancement Proposal process to manage the design and justification - of complex changes, or changes with a potentially significant impact on - end users - -As a result of the additional responsibilities they accept, core developers -gain the privilege of being able to approve proposed changes, as well as being -able to reject them as inappropriate. Core developers are also able to request -that even already merged changes be escalated to python-dev for further -discussion, and potentially even reverted prior to release. - -Becoming a core developer isn't a binary "all-or-nothing" status - CPython -is a large project, and different core developers accept responsibility for -making design and development decisions in different areas (as documented -in the :ref:`experts` and :ref:`developers`). Gaining Commit Privileges -------------------------- +========================= The steps to gaining commit privileges are: @@ -93,86 +56,3 @@ The steps to gaining commit privileges are: membership will be sent to python-committers .. _Code of Conduct: https://www.python.org/psf/conduct/ - - -Mailing Lists -''''''''''''' - -You are expected to subscribe to python-committers, python-dev, -python-checkins, and one of new-bugs-announce or python-bugs-list. See -:ref:`communication` for links to these mailing lists. - - -.. _contributor_agreement: - -Sign a Contributor Agreement -'''''''''''''''''''''''''''' - -Submitting a `contributor form for Python`_ licenses any code you contribute to -the Python Software Foundation. While you retain the copyright, giving the PSF -the ability to license your code means it can be put under the PSF license so -it can be legally distributed with Python. - -This is a very important step! Hopefully you have already submitted a -contributor agreement if you have been submitting patches. But if you have not -done this yet, it is best to do this ASAP, probably before you even do your -first commit so as to not forget. Also do not forget to enter your GitHub -username into your details on the issue tracker. - - -.. _contributor form for Python: https://www.python.org/psf/contrib/ - - - -Pull Request merging -'''''''''''''''''''' - -Once you have your commit privileges on GitHub you will be able to accept -pull requests on GitHub. You should plan to continue to submit your own -changes through pull requests as if you weren't a core developer to benefit -from various things such as automatic integration testing, but you -can accept your own pull requests if you feel comfortable doing so. - - -Responsibilities ----------------- - -As a core developer, there are certain things that are expected of you. - -First and foremost, be a good person. This might sound melodramatic, but you -are now a member of the Python project and thus represent the project and your -fellow core developers whenever you discuss Python with anyone. We have a -reputation for being a very nice group of people and we would like to keep it -that way. Core developers responsibilities include following the `PSF Code of -Conduct`_. - -Second, please be prompt in responding to questions. Many contributors to Python -are volunteers so what little free time they can dedicate to Python should be -spent being productive. If you have been asked to respond to an issue or answer -a question and you put it off it ends up stalling other people's work. It is -completely acceptable to say you are too busy, but you need to say that instead -of leaving people waiting for an answer. This also applies to anything you -do on the issue tracker. - -Third, please list what areas you want to be considered an expert in the -:ref:`experts`. This allows triagers to direct issues to you which involve -an area you are an expert in. But, as stated in the second point above, if you -do not have the time to answer questions promptly then please remove yourself as -needed from the file so that you will not be bothered in the future. Once again, -we all understand how life gets in the way, so no one will be insulted if you -remove yourself from the list. - -Fourth, please consider whether or not you wish to add your name to the -:ref:`motivations` list. Core contributor participation in the list helps the -wider Python community to better appreciate the perspectives currently -represented amongst the core development team, the Python Software Foundation -to better assess the sustainability of current contributions to CPython core -development, and also serves as a referral list for organisations seeking -commercial Python support from the core development community. - -And finally, enjoy yourself! Contributing to open source software should be fun -(overall). If you find yourself no longer enjoying the work then either take a -break or figure out what you need to do to make it enjoyable again. - - -.. _PSF Code of Conduct: https://www.python.org/psf/conduct/ diff --git a/core-developers/index.rst b/core-developers/index.rst index 3a037151fb..cf743c405c 100644 --- a/core-developers/index.rst +++ b/core-developers/index.rst @@ -5,6 +5,7 @@ Core Developers .. toctree:: :maxdepth: 5 + responsibilities committing experts developer-log diff --git a/core-developers/responsibilities.rst b/core-developers/responsibilities.rst new file mode 100644 index 0000000000..da51b24636 --- /dev/null +++ b/core-developers/responsibilities.rst @@ -0,0 +1,122 @@ +.. _responsibilities: + +================ +Responsibilities +================ + +As contributors to the CPython project, our shared responsibility is to +collaborate constructively with other contributors, including core developers. +This responsibility covers all forms of contribution, whether that's submitting +patches to the implementation or documentation, reviewing other peoples' +patches, triaging issues on the issue tracker, or discussing design and +development ideas on the core mailing lists. + +Core developers accept key additional responsibilities around the ongoing +management of the project: + +* core developers bear the additional responsibility of handling the + consequences of accepting a change into the code base or documentation. + That includes reverting or fixing it if it causes problems in the + Buildbot fleet or someone spots a problem in post-commit review, as well + as helping out the release manager in resolving any problems found during + the pre-release testing cycle. While all contributors are free to help out + with this part of the process, and it is most welcome when they do, the + actual responsibility rests with the core developer that merged the change +* core developers also bear the primary responsibility for deciding when + changes proposed on the issue tracker should be escalated to python-ideas + or python-dev for wider discussion, as well as suggesting the use of the + Python Enhancement Proposal process to manage the design and justification + of complex changes, or changes with a potentially significant impact on + end users + +As a result of the additional responsibilities they accept, core developers +gain the privilege of being able to approve proposed changes, as well as being +able to reject them as inappropriate. Core developers are also able to request +that even already merged changes be escalated to python-dev for further +discussion, and potentially even reverted prior to release. + +Becoming a core developer isn't a binary "all-or-nothing" status - CPython +is a large project, and different core developers accept responsibility for +making design and development decisions in different areas (as documented +in the :ref:`experts` and :ref:`developers`). + + +Mailing Lists +============= + +You are expected to subscribe to python-committers, python-dev, +python-checkins, and one of new-bugs-announce or python-bugs-list. See +:ref:`communication` for links to these mailing lists. + + +.. _contributor_agreement: + +Sign a Contributor Agreement +============================ + +Submitting a `contributor form for Python`_ licenses any code you contribute to +the Python Software Foundation. While you retain the copyright, giving the PSF +the ability to license your code means it can be put under the PSF license so +it can be legally distributed with Python. + +This is a very important step! Hopefully you have already submitted a +contributor agreement if you have been submitting patches. But if you have not +done this yet, it is best to do this ASAP, probably before you even do your +first commit so as to not forget. Also do not forget to enter your GitHub +username into your details on the issue tracker. + + +.. _contributor form for Python: https://www.python.org/psf/contrib/ + + +Pull Request merging +==================== + +Once you have your commit privileges on GitHub you will be able to accept +pull requests on GitHub. You should plan to continue to submit your own +changes through pull requests as if you weren't a core developer to benefit +from various things such as automatic integration testing, but you +can accept your own pull requests if you feel comfortable doing so. + + +Expectations +============ + +As a core developer, there are certain things that are expected of you. + +First and foremost, be a good person. This might sound melodramatic, but you +are now a member of the Python project and thus represent the project and your +fellow core developers whenever you discuss Python with anyone. We have a +reputation for being a very nice group of people and we would like to keep it +that way. Core developers responsibilities include following the `PSF Code of +Conduct`_. + +Second, please be prompt in responding to questions. Many contributors to Python +are volunteers so what little free time they can dedicate to Python should be +spent being productive. If you have been asked to respond to an issue or answer +a question and you put it off it ends up stalling other people's work. It is +completely acceptable to say you are too busy, but you need to say that instead +of leaving people waiting for an answer. This also applies to anything you +do on the issue tracker. + +Third, please list what areas you want to be considered an expert in the +:ref:`experts`. This allows triagers to direct issues to you which involve +an area you are an expert in. But, as stated in the second point above, if you +do not have the time to answer questions promptly then please remove yourself as +needed from the file so that you will not be bothered in the future. Once again, +we all understand how life gets in the way, so no one will be insulted if you +remove yourself from the list. + +Fourth, please consider whether or not you wish to add your name to the +:ref:`motivations` list. Core contributor participation in the list helps the +wider Python community to better appreciate the perspectives currently +represented amongst the core development team, the Python Software Foundation +to better assess the sustainability of current contributions to CPython core +development, and also serves as a referral list for organisations seeking +commercial Python support from the core development community. + +And finally, enjoy yourself! Contributing to open source software should be fun +(overall). If you find yourself no longer enjoying the work then either take a +break or figure out what you need to do to make it enjoyable again. + +.. _PSF Code of Conduct: https://www.python.org/psf/conduct/ From 882d48c85a1e555e59b52d5304609fccc7b09355 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 3 Jul 2022 23:07:40 +0100 Subject: [PATCH 16/21] Split out supported versions --- developer-workflow/development-cycle.rst | 24 +-------- index.rst | 44 +--------------- versions.rst | 64 ++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 65 deletions(-) create mode 100644 versions.rst diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index 460c633d2e..a0481c8bf0 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -126,29 +126,7 @@ is frozen and no longer has a branch in the repo. The final state of the end-of-lifed branch is recorded as a tag with the same name as the former branch, e.g. ``3.3`` or ``2.6``. -For reference, here are the Python versions that most recently reached their end-of-life: - -+------------------+--------------+----------------+----------------+----------------------------------+ -| Branch | Schedule | First release | End-of-life | Release manager | -+==================+==============+================+================+==================================+ -| 3.6 | :pep:`494` | 2016-12-23 | 2021-12-23 | Ned Deily | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 3.5 | :pep:`478` | 2015-09-13 | 2020-09-30 | Larry Hastings | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 3.4 | :pep:`429` | 2014-03-16 | 2019-03-18 | Larry Hastings | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 3.3 | :pep:`398` | 2012-09-29 | 2017-09-29 | Georg Brandl, Ned Deily (3.3.7+) | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 3.2 | :pep:`392` | 2011-02-20 | 2016-02-20 | Georg Brandl | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 3.1 | :pep:`375` | 2009-06-27 | 2012-04-09 | Benjamin Peterson | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 3.0 | :pep:`361` | 2008-12-03 | 2009-06-27 | Barry Warsaw | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 2.7 | :pep:`373` | 2010-07-03 | 2020-01-01 | Benjamin Peterson | -+------------------+--------------+----------------+----------------+----------------------------------+ -| 2.6 | :pep:`361` | 2008-10-01 | 2013-10-29 | Barry Warsaw | -+------------------+--------------+----------------+----------------+----------------------------------+ +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 `_. diff --git a/index.rst b/index.rst index 24d26bbe12..6355cdeb56 100644 --- a/index.rst +++ b/index.rst @@ -89,51 +89,10 @@ contributing to Python: * PEPs_ (Python Enhancement Proposals) * :ref:`gitbootcamp` -.. _branchstatus: - Status of Python branches ------------------------- -+------------------+--------------+-------------+----------------+----------------+-----------------------+ -| Branch | Schedule | Status | First release | End-of-life | Release manager | -+==================+==============+=============+================+================+=======================+ -| main | TBA | features | *2023-10-03* | *2028-10* | Thomas Wouters | -+------------------+--------------+-------------+----------------+----------------+-----------------------+ -| 3.11 | :pep:`664` | bugfix | *2022-10-03* | *2027-10* | Pablo Galindo Salgado | -+------------------+--------------+-------------+----------------+----------------+-----------------------+ -| 3.10 | :pep:`619` | bugfix | 2021-10-04 | *2026-10* | Pablo Galindo Salgado | -+------------------+--------------+-------------+----------------+----------------+-----------------------+ -| 3.9 | :pep:`596` | security | 2020-10-05 | *2025-10* | Łukasz Langa | -+------------------+--------------+-------------+----------------+----------------+-----------------------+ -| 3.8 | :pep:`569` | security | 2019-10-14 | *2024-10* | Łukasz Langa | -+------------------+--------------+-------------+----------------+----------------+-----------------------+ -| 3.7 | :pep:`537` | security | 2018-06-27 | *2023-06-27* | Ned Deily | -+------------------+--------------+-------------+----------------+----------------+-----------------------+ - -.. Remember to update the end-of-life table in devcycle.rst. - -Dates in *italic* are scheduled and can be adjusted. - -The main branch is currently the future Python 3.12, and is the only -branch that accepts new features. The latest release for each Python -version can be found on the `download page `_. - -Status: - -:features: new features, bugfixes, and security fixes are accepted. -:prerelease: feature fixes, bugfixes, and security fixes are accepted for the - upcoming feature release. -:bugfix: bugfixes and security fixes are accepted, new binaries are still - released. (Also called **maintenance** mode or **stable** release) -:security: only security fixes are accepted and no more binaries are released, - but new source-only versions can be released -:end-of-life: release cycle is frozen; no further changes can be pushed to it. - -See also the :ref:`devcycle` page for more information about branches. - -By default, the end-of-life is scheduled 5 years after the first release, -but can be adjusted by the release manager of each branch. All Python 2 -versions have reached end-of-life. +Moved to :ref:`versions` .. _contributing: @@ -305,6 +264,7 @@ Full Table of Contents core-developers/index internals/index advanced-tools/index + versions appendix .. _Buildbot status: https://www.python.org/dev/buildbot/ diff --git a/versions.rst b/versions.rst new file mode 100644 index 0000000000..301bdead22 --- /dev/null +++ b/versions.rst @@ -0,0 +1,64 @@ +.. _versions: +.. _branchstatus: + +========================= +Status of Python Versions +========================= + +The main branch is currently the future Python 3.12, and is the only +branch that accepts new features. The latest release for each Python +version can be found on the `download page `_. + + +Supported Versions +================== + +Dates shown in *italic* are scheduled and can be adjusted. + +====== ========== ======== ============= ============ ===================== +Branch Schedule Status First release End-of-life Release manager +====== ========== ======== ============= ============ ===================== +main TBA features *2023-10-03* *2028-10* Thomas Wouters +3.11 :pep:`664` bugfix *2022-10-03* *2027-10* Pablo Galindo Salgado +3.10 :pep:`619` bugfix 2021-10-04 *2026-10* Pablo Galindo Salgado +3.9 :pep:`596` security 2020-10-05 *2025-10* Łukasz Langa +3.8 :pep:`569` security 2019-10-14 *2024-10* Łukasz Langa +3.7 :pep:`537` security 2018-06-27 *2023-06-27* Ned Deily +====== ========== ======== ============= ============ ===================== + + +Unsupported versions +==================== + +====== ========== =========== ============= =========== ================================ +Branch Schedule Status First release End-of-life Release manager +====== ========== =========== ============= =========== ================================ +3.6 :pep:`494` end-of-life 2016-12-23 2021-12-23 Ned Deily +3.5 :pep:`478` end-of-life 2015-09-13 2020-09-30 Larry Hastings +3.4 :pep:`429` end-of-life 2014-03-16 2019-03-18 Larry Hastings +3.3 :pep:`398` end-of-life 2012-09-29 2017-09-29 Georg Brandl, Ned Deily (3.3.7+) +3.2 :pep:`392` end-of-life 2011-02-20 2016-02-20 Georg Brandl +3.1 :pep:`375` end-of-life 2009-06-27 2012-04-09 Benjamin Peterson +3.0 :pep:`361` end-of-life 2008-12-03 2009-06-27 Barry Warsaw +2.7 :pep:`373` end-of-life 2010-07-03 2020-01-01 Benjamin Peterson +2.6 :pep:`361` end-of-life 2008-10-01 2013-10-29 Barry Warsaw +====== ========== =========== ============= =========== ================================ + + +Status key +========== + +:features: new features, bugfixes, and security fixes are accepted. +:prerelease: feature fixes, bugfixes, and security fixes are accepted for the + upcoming feature release. +:bugfix: bugfixes and security fixes are accepted, new binaries are still + released. (Also called **maintenance** mode or **stable** release) +:security: only security fixes are accepted and no more binaries are released, + but new source-only versions can be released +:end-of-life: release cycle is frozen; no further changes can be pushed to it. + +See also the :ref:`devcycle` page for more information about branches. + +By default, the end-of-life is scheduled 5 years after the first release, +but can be adjusted by the release manager of each branch. All Python 2 +versions have reached end-of-life. From b960548236448d1758ec74a4aa26a1e6689c3a6c Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 21:19:23 +0100 Subject: [PATCH 17/21] Update headings and underlines --- advanced-tools/clang.rst | 4 +- advanced-tools/gdb.rst | 9 +-- core-developers/become-core-developer.rst | 6 +- core-developers/experts.rst | 15 +++-- core-developers/motivations.rst | 11 ++-- developer-workflow/communication-channels.rst | 37 ++++++++----- developer-workflow/extension-modules.rst | 5 +- developer-workflow/grammar.rst | 5 +- developer-workflow/porting.rst | 5 +- documentation/help-documenting.rst | 7 ++- documentation/start-documenting.rst | 6 +- getting-started/fixing-issues.rst | 1 + getting-started/pull-request-lifecycle.rst | 33 +++++------ getting-started/setup-building.rst | 6 +- internals/compiler.rst | 29 +++++----- internals/exploring.rst | 9 +-- internals/garbage-collector.rst | 23 ++++---- internals/parser.rst | 55 ++++++++++--------- testing/buildbots.rst | 19 ++++--- testing/coverage.rst | 9 +-- testing/new-buildbot-worker.rst | 22 ++++---- testing/run-write-tests.rst | 14 +++-- testing/silence-warnings.rst | 1 + triage/github-bpo-faq.rst | 25 +++++---- triage/issue-tracker.rst | 6 +- triage/labels.rst | 45 +++++++-------- triage/triaging.rst | 6 +- 27 files changed, 222 insertions(+), 191 deletions(-) diff --git a/advanced-tools/clang.rst b/advanced-tools/clang.rst index 74171f0288..d626c33ea7 100644 --- a/advanced-tools/clang.rst +++ b/advanced-tools/clang.rst @@ -1,8 +1,8 @@ .. _clang: -*************************** +=========================== Dynamic Analysis with Clang -*************************** +=========================== .. highlight:: bash diff --git a/advanced-tools/gdb.rst b/advanced-tools/gdb.rst index 8a1fc4504e..df4d71e738 100644 --- a/advanced-tools/gdb.rst +++ b/advanced-tools/gdb.rst @@ -1,6 +1,7 @@ .. _gdb: -gdb Support +=========== +GDB Support =========== .. highlight:: none @@ -17,7 +18,7 @@ limitation. gdb 7 and later ---------------- +=============== In gdb 7, support for `extending gdb with Python `_ was @@ -300,7 +301,7 @@ thread is doing at the Python level:: gdb 6 and earlier ------------------ +================= The file at ``Misc/gdbinit`` contains a gdb configuration file which provides extra commands when working with a CPython process. To register these commands @@ -311,7 +312,7 @@ from your gdb session. Updating auto-load-safe-path to allow test_gdb to run ------------------------------------------------------ +===================================================== ``test_gdb`` attempts to automatically load additional Python specific hooks into gdb in order to test them. Unfortunately, the command line diff --git a/core-developers/become-core-developer.rst b/core-developers/become-core-developer.rst index e5c862fb96..fd762b568f 100644 --- a/core-developers/become-core-developer.rst +++ b/core-developers/become-core-developer.rst @@ -1,8 +1,8 @@ .. _coredev: -================================ - How to Become a Core Developer -================================ +============================== +How to Become a Core Developer +============================== What it Takes ============= diff --git a/core-developers/experts.rst b/core-developers/experts.rst index 2ed035ef4c..5683e8bc2d 100644 --- a/core-developers/experts.rst +++ b/core-developers/experts.rst @@ -1,5 +1,6 @@ .. _experts: +============= Experts Index ============= @@ -44,7 +45,8 @@ not feel qualified to make a decision in a particular context. Stdlib ------- +====== + ==================== ============================================= Module Maintainers ==================== ============================================= @@ -276,7 +278,8 @@ zlib Yhg1s, gpshead* Tools ------ +===== + ================== =========== Tool Maintainers ================== =========== @@ -286,7 +289,8 @@ PEG Generator gvanrossum, pablogsal, lysnikolaou Platforms ---------- +========= + =================== =========== Platform Maintainers =================== =========== @@ -305,7 +309,8 @@ JVM/Java frank.wierzbicki^ Miscellaneous -------------- +============= + ================== ========================================================== Interest Area Maintainers ================== ========================================================== @@ -359,6 +364,6 @@ version control merwok, ezio-melotti Documentation Translations --------------------------- +========================== For a list of translators, see :ref:`this table about translations `. diff --git a/core-developers/motivations.rst b/core-developers/motivations.rst index 214853b187..41e3156ecb 100644 --- a/core-developers/motivations.rst +++ b/core-developers/motivations.rst @@ -1,7 +1,8 @@ .. _motivations: -Core Developer Motivations and Affiliations -=========================================== +============================ +Motivations and Affiliations +============================ CPython core developers participate in the core development process for a variety of reasons. Being accepted as a core developer indicates that @@ -29,7 +30,7 @@ For more information on the origins and purpose of this page, see .. _published-motivations: Published entries ------------------ +================= The following core developers have chosen to provide additional details regarding their professional affiliations and (optionally) other reasons for @@ -270,7 +271,7 @@ participating in the CPython core development process: .. _goals-of-the-motivations-page: Goals of this page ------------------- +================== The `issue metrics`_ automatically collected by the CPython issue tracker strongly suggest that the current core development process is bottlenecked on @@ -329,7 +330,7 @@ time contributing to CPython development. Limitations on scope --------------------- +==================== * Specific technical areas of interest for core developers should be captured in the :ref:`Experts Index `. diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 4d9a061f30..4cdbb27600 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -1,5 +1,6 @@ .. _communication: +============================== Following Python's Development ============================== @@ -8,7 +9,8 @@ mailing lists, but also other forms. Standards of behaviour in these communication channels ------------------------------------------------------- +====================================================== + We try to foster environments of mutual respect, tolerance and encouragement, as described in the PSF's `Diversity Statement`_. Abiding by the guidelines in this document and asking questions or posting suggestions in the @@ -22,7 +24,7 @@ in return. .. _mailinglists: Mailing Lists -------------- +============= python-dev_ is the primary mailing list for discussions about Python's development. The list is open to the public and is subscribed to by all core @@ -95,7 +97,7 @@ RSS feed readers. .. _discourse_discuss: Discourse (discuss.python.org web forum) ----------------------------------------- +======================================== We have our own `Discourse`_ forum for both developers and users. This forum complements the `python-dev`_, `python-ideas`_, `python-help`_, and @@ -113,7 +115,8 @@ It is also a common venue for the core developer promotion votes (this category is equivalent to the python-committers mailing list). Tutorials for new users -''''''''''''''''''''''' +------------------------- + To start a topic or participate in any discussions in the forum, sign up and create an account using an email address or GitHub account. You can do so by clicking the "Sign Up" button on the top right hand corner of the `Discourse`_ @@ -144,7 +147,7 @@ dots under the message and then on the ⚐ icon. You can also mention the Reading topics -''''''''''''''' +----------------- Click a topic title and read down the list of replies in chronological order, following links or previewing replies and quotes as you go. Use your mouse to scroll the screen, or use the timeline scroll bar on the right which also shows @@ -153,10 +156,11 @@ bottom progress bar to expand it. 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 page, and use the notification button 🔔 above the topic list, @@ -168,7 +172,8 @@ 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 of the timeline. You can also do so at the bottom of each topic. @@ -176,13 +181,15 @@ 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 `_. This allows you to make adjustments according to categories, users, and tags. Enabling mailing list mode -'''''''''''''''''''''''''' +-------------------------- + 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. @@ -197,7 +204,7 @@ mailing list mode" and save changes. Discord (private chat server) ------------------------------ +============================= For more real-time discussions, the core development team have a private Discord server available. Core developers, Steering Council members, triagers, and @@ -235,7 +242,7 @@ set a specific `Server Nickname`_ IRC ---- +=== Some core developers still participate in the ``#python-dev`` IRC channel on ``irc.libera.chat``. This is not a place to ask for help with Python, but to @@ -244,7 +251,7 @@ discuss issues related to Python's own development. See also the Blogs ------ +===== Several core developers are active bloggers and discuss Python's development that way. You can find their blogs (and various other developers who use Python) @@ -252,7 +259,7 @@ at https://planetpython.org/. 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 `_ @@ -260,7 +267,7 @@ about this topic that sets out to help everyone set reasonable expectations of e order to make open source pleasant for everyone involved. Additional Repositories ------------------------ +======================= `Python Core Workflow`_ hosts the codebase for tools such as `cherry_picker`_ and `blurb`_. diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index 0d6eee609c..f69eabefdb 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -1,7 +1,8 @@ .. _extensions: -Updating standard library extension modules -=========================================== +================================== +Standard Library Extension Modules +================================== In this section, we could explain how to write a CPython extension with the C language, but the topic can take a complete book. diff --git a/developer-workflow/grammar.rst b/developer-workflow/grammar.rst index 06d1575573..7ff1ed12ad 100644 --- a/developer-workflow/grammar.rst +++ b/developer-workflow/grammar.rst @@ -1,10 +1,11 @@ .. _grammar: +========================== Changing CPython's Grammar ========================== Abstract --------- +======== There's more to changing Python's grammar than editing :file:`Grammar/python.gram`. Here's a checklist. @@ -20,7 +21,7 @@ For more information on how to use the new parser, check the :ref:`section on how to use CPython's parser `. Checklist ---------- +========= Note: sometimes things mysteriously don't work. Before giving up, try ``make clean``. diff --git a/developer-workflow/porting.rst b/developer-workflow/porting.rst index fdf01eef91..3efbb33799 100644 --- a/developer-workflow/porting.rst +++ b/developer-workflow/porting.rst @@ -1,7 +1,8 @@ .. _porting: -Porting Python to a new platform --------------------------------- +========================= +Porting to a New Platform +========================= The first step is to familiarize yourself with the development toolchain on the platform in question, notably the C compiler. Make sure you can compile and diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index 2a804990cc..a28b5ff2ca 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -1,5 +1,6 @@ .. _docquality: +========================== Helping with Documentation ========================== @@ -20,7 +21,7 @@ detailed information on how to write documentation and submit changes. Python Documentation --------------------- +==================== The :ref:`Documenting Python ` section covers the details of how Python's documentation works. It includes information about the markup @@ -43,7 +44,7 @@ mailing list discusses the documentation toolchain, projects, and standards. Helping with documentation issues ---------------------------------- +================================= If you look at `documentation issues`_ on the `issue tracker`_, you will find various documentation problems that may need work. Issues vary from @@ -67,7 +68,7 @@ you will learn the workflow for documentation pull requests. Proofreading ------------- +============ While an issue filed on the `issue tracker`_ means there is a known issue somewhere, that does not mean there are not other issues lurking about in the diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 6c9fcf38f3..1648eef945 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -1,8 +1,8 @@ .. _documenting: -================== -Documenting Python -================== +=============== +Getting Started +=============== .. highlight:: rest diff --git a/getting-started/fixing-issues.rst b/getting-started/fixing-issues.rst index 1486275787..14eb5439b2 100644 --- a/getting-started/fixing-issues.rst +++ b/getting-started/fixing-issues.rst @@ -1,5 +1,6 @@ .. _fixingissues: +================================= Fixing "easy" Issues (and Beyond) ================================= diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index e7964df654..667261e49e 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -1,13 +1,14 @@ .. _patch: .. _pullrequest: +=========================== Lifecycle of a Pull Request =========================== .. highlight:: bash Introduction ------------- +============ CPython uses a workflow based on pull requests. What this means is that you create a branch in Git, make your changes, push those changes @@ -18,7 +19,7 @@ the official CPython repository (``upstream``). .. _pullrequest-quickguide: Quick Guide ------------ +=========== `Clear communication`_ is key to contributing to any project, especially an `Open Source`_ project like CPython. @@ -68,7 +69,7 @@ Here is a quick overview of how you can contribute to CPython: .. _pullrequest-steps: Step-by-step Guide ------------------- +================== You should have already :ref:`set up your system `, :ref:`got the source code `, and :ref:`built Python `. @@ -144,7 +145,7 @@ You should have already :ref:`set up your system `, .. _resolving-merge-conflicts: Resolving Merge Conflicts -''''''''''''''''''''''''' +------------------------- When merging changes from different branches (or variants of a branch on different repos), the two branches may contain incompatible changes to one @@ -173,7 +174,7 @@ for a detailed technical explanation. .. _good-prs: Making Good PRs ---------------- +=============== When creating a pull request for submission, there are several things that you should do to help ensure that your pull request is accepted. @@ -217,7 +218,7 @@ additions/changes should be included. .. _patchcheck: ``patchcheck`` --------------- +============== ``patchcheck`` is a simple automated patch checklist that guides a developer through the common patch generation checks. To run ``patchcheck``: @@ -257,7 +258,7 @@ making a complete patch. .. _good-commits: Making Good Commits -------------------- +=================== Each feature or bugfix should be addressed by a single pull request, and for each pull request there may be several commits. In particular: @@ -297,7 +298,7 @@ request. .. _cla: Licensing ---------- +========= To accept your change we must have your formal approval for distributing your work under the `PSF license`_. Therefore, you need to sign a @@ -328,7 +329,7 @@ Here are the steps needed in order to sign the CLA: Submitting ----------- +========== Once you are satisfied with your work you will want to commit your changes to your branch. In general you can run ``git commit -a`` and @@ -369,7 +370,7 @@ The commits will be squashed when the pull request is merged. Converting an Existing Patch from b.p.o to GitHub -------------------------------------------------- +================================================= When a patch exists in the `issue tracker`_ that should be converted into a GitHub pull request, please first ask the original patch author to prepare @@ -385,7 +386,7 @@ on how to properly add the co-author info. See also :ref:`Applying a Patch to Git `. Reviewing ---------- +========= To begin with, please be patient! There are many more people submitting pull requests than there are people capable of reviewing @@ -410,7 +411,7 @@ thus iterate until a satisfactory solution has emerged. How to Review a Pull Request -'''''''''''''''''''''''''''' +---------------------------- One of the bottlenecks in the Python development process is the lack of code reviews. @@ -451,7 +452,7 @@ code and leave comments in the pull request or issue tracker. 'merge-ready', you should always make sure the entire test suite passes. Leaving a Pull Request Review on GitHub ---------------------------------------- +======================================= When you review a pull request, you should provide additional details and context of your review process. @@ -467,7 +468,7 @@ Instead of simply "approving" the pull request, leave comments. For example: so will make it easier for the PR author to find the good in your comments. Dismissing Review from Another Core Developer ---------------------------------------------- +============================================= A core developer can dismiss another core developer's review if they confirmed that the requested changes have been made. When a core developer has assigned @@ -476,7 +477,7 @@ the PR, and their review should not be dismissed. Committing/Rejecting --------------------- +==================== Once your pull request has reached an acceptable state (and thus considered "accepted"), it will either be merged or rejected. If it is rejected, please @@ -492,7 +493,7 @@ it is warranted. Crediting ---------- +========= Non-trivial contributions are credited in the ``Misc/ACKS`` file (and, most often, in a contribution's news entry as well). You may be diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 4c3d2e52ba..1505283920 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1,8 +1,8 @@ .. _setup: -=============== -Getting Started -=============== +================== +Setup and Building +================== .. highlight:: console diff --git a/internals/compiler.rst b/internals/compiler.rst index be39f2cd71..0e31e1be47 100644 --- a/internals/compiler.rst +++ b/internals/compiler.rst @@ -1,12 +1,13 @@ .. _compiler: -Design of CPython's Compiler -============================ +=============== +Compiler Design +=============== .. highlight:: none Abstract --------- +======== In CPython, the compilation from source code to bytecode involves several steps: @@ -24,7 +25,7 @@ to read some source to have an exact understanding of all details. Parsing -------- +======= As of Python 3.9, Python's parser is a PEG parser of a somewhat unusual design (since its input is a stream of tokens rather than a @@ -38,7 +39,7 @@ these (see :ref:`grammar`). Abstract Syntax Trees (AST) ---------------------------- +=========================== .. _compiler-ast-trees: @@ -127,7 +128,7 @@ initializes the *name*, *args*, *body*, and *attributes* fields. Memory Management ------------------ +================= Before discussing the actual implementation of the compiler, a discussion of how memory is handled is in order. To make memory management simple, an arena @@ -161,7 +162,7 @@ the arena about it by calling ``PyArena_AddPyObject()``. Source Code to AST ------------------- +================== The AST is generated from source code using the function ``_PyParser_ASTFromString()`` or ``_PyParser_ASTFromFile()`` @@ -287,7 +288,7 @@ number is passed as the last parameter to each ``stmt_ty`` function. Control Flow Graphs -------------------- +=================== A *control flow graph* (often referenced by its acronym, CFG) is a directed graph that models the flow of a program. A node of a CFG is @@ -333,7 +334,7 @@ following the edges. AST to CFG to Bytecode ----------------------- +====================== With the AST created, the next step is to create the CFG. The first step is to convert the AST to Python bytecode without having jump targets @@ -449,7 +450,7 @@ handled by calling ``assemble()``. Introducing New Bytecode ------------------------- +======================== Sometimes a new feature requires a new opcode. But adding new bytecode is not as simple as just suddenly introducing new bytecode in the AST -> @@ -507,7 +508,7 @@ for recompiling generated C files. Code Objects ------------- +============ The result of ``PyAST_CompileObject()`` is a ``PyCodeObject`` which is defined in :file:`Include/code.h`. And with that you now have executable Python bytecode! @@ -518,7 +519,7 @@ statement in ``_PyEval_EvalFrameDefault()``. Important Files ---------------- +=============== + Parser/ @@ -655,7 +656,7 @@ Important Files Known Compiler-related Experiments ----------------------------------- +================================== This section lists known experiments involving the compiler (including bytecode). @@ -675,7 +676,7 @@ thanks to having to support both classic and new-style classes. References ----------- +========== .. [Wang97] Daniel C. Wang, Andrew W. Appel, Jeff L. Korn, and Chris S. Serra. `The Zephyr Abstract Syntax Description Language.`_ diff --git a/internals/exploring.rst b/internals/exploring.rst index 7d5f908a2f..f27c150c0e 100644 --- a/internals/exploring.rst +++ b/internals/exploring.rst @@ -1,7 +1,8 @@ .. _exploring: -Exploring CPython's Internals -============================= +======================== +Exploring the Internals +======================== This is a quick guide for people who are interested in learning more about CPython's internals. It provides a summary of the source code structure @@ -9,7 +10,7 @@ and contains references to resources providing a more in-depth view. CPython Source Code Layout --------------------------- +========================== This guide gives an overview of CPython's code structure. It serves as a summary of file locations for modules and builtins. @@ -49,7 +50,7 @@ Some exceptions: Additional References ---------------------- +===================== For over 20 years the CPython code base has been changing and evolving. Here's a sample of resources about the architecture of CPython aimed at diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst index c4cecdb79f..c058d79332 100644 --- a/internals/garbage-collector.rst +++ b/internals/garbage-collector.rst @@ -1,15 +1,16 @@ .. _gc: .. _garbage_collector: -Design of CPython's Garbage Collector -===================================== +======================== +Garbage Collector Design +======================== :Author: Pablo Galindo Salgado .. highlight:: none Abstract --------- +======== The main garbage collection algorithm used by CPython is reference counting. The basic idea is that CPython counts how many different places there are that have a reference to an @@ -54,7 +55,7 @@ unreachable. This is the cyclic garbage collector, usually called just Garbage Collector (GC), even though reference counting is also a form of garbage collection. Memory layout and object structure ----------------------------------- +================================== Normally the C structure supporting a regular Python object looks as follows: @@ -119,7 +120,7 @@ the type is immutable, a ``tp_clear`` implementation must also be provided. Identifying reference cycles ----------------------------------------------- +============================ The algorithm that CPython uses to detect those reference cycles is implemented in the ``gc`` module. The garbage collector **only focuses** @@ -242,7 +243,7 @@ number of objects, number of pointers, or the lengths of pointer chains. Apart the GC algorithms require. Why moving unreachable objects is better -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------- It sounds logical to move the unreachable objects under the premise that most objects are usually reachable, until you think about it: the reason it pays isn't actually @@ -267,7 +268,7 @@ unbounded number of moves across an unbounded number of later collections. The o time the cost can be higher is the first time the chain is scanned. Destroying unreachable objects ------------------------------- +============================== Once the GC knows the list of unreachable objects, a very delicate process starts with the objective of completely destroying these objects. Roughly, the process @@ -298,7 +299,7 @@ follows these steps in order: objects. Optimization: generations -------------------------- +========================= In order to limit the time each garbage collection takes, the GC uses a popular optimization: generations. The main idea behind this concept is the assumption that @@ -369,7 +370,7 @@ specifically in a generation by calling ``gc.collect(generation=NUM)``. Collecting the oldest generation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- In addition to the various configurable thresholds, the GC only triggers a full collection of the oldest generation if the ratio ``long_lived_pending / long_lived_total`` @@ -388,7 +389,7 @@ in the total number of objects (the effect of which can be summarized thusly: grows, but we do fewer and fewer of them"). Optimization: reusing fields to save memory -------------------------------------------- +=========================================== In order to save memory, the two linked list pointers in every object with GC support are reused for several purposes. This is a common optimization known @@ -437,7 +438,7 @@ of ``PyGC_Head`` discussed in the `Memory layout and object structure`_ section: ``NEXT_MASK_UNREACHABLE`` flag) are employed. Optimization: delay tracking containers ---------------------------------------- +======================================= Certain types of containers cannot participate in a reference cycle, and so do not need to be tracked by the garbage collector. Untracking these objects diff --git a/internals/parser.rst b/internals/parser.rst index c52590bc31..951b62198b 100644 --- a/internals/parser.rst +++ b/internals/parser.rst @@ -1,14 +1,15 @@ .. _parser: -Guide to CPython's Parser -========================= +=================== +Guide to the Parser +=================== :Author: Pablo Galindo Salgado .. highlight:: none Abstract --------- +======== The Parser in CPython is currently a `PEG (Parser Expression Grammar) `_ parser. The first @@ -24,7 +25,7 @@ modifying the grammar file and developers rarely need to interact with the parser generator itself other than use it to generate the parser. How PEG Parsers Work --------------------- +==================== .. _how-peg-parsers-work: @@ -73,7 +74,7 @@ table-based. Key ideas -~~~~~~~~~ +--------- .. important:: Don't try to reason about a PEG grammar in the same way you would to with an EBNF @@ -92,7 +93,7 @@ Key ideas Consequences or the ordered choice operator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------- .. _consequences-of-ordered-choice: @@ -143,7 +144,7 @@ In this case, if the input string doesn't have an ``'else' block``, the first al will fail and the second will be attempted without said part. Syntax ------- +====== The grammar consists of a sequence of rules of the form: :: @@ -159,7 +160,7 @@ If the return type is omitted, then a ``void *`` is returned in C and an ``Any`` in Python. Grammar Expressions -~~~~~~~~~~~~~~~~~~~ +------------------- ``# comment`` ''''''''''''' @@ -288,7 +289,7 @@ alternative won’t be considered, even if some_rule or ``)`` fail to be parsed. Left recursion -~~~~~~~~~~~~~~ +-------------- PEG parsers normally do not support left recursion but CPython's parser generator implements a technique similar to the one described in Medeiros et al. @@ -306,7 +307,7 @@ and "hidden left-recursion" like:: rule: 'optional'? rule '@' some_other_rule Variables in the Grammar -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ A sub-expression can be named by preceding it with an identifier and an ``=`` sign. The name can then be used in the action (see below), like this: :: @@ -314,7 +315,7 @@ A sub-expression can be named by preceding it with an identifier and an rule_name[return_type]: '(' a=some_other_rule ')' { a } Grammar actions -~~~~~~~~~~~~~~~ +--------------- .. _peg-grammar-actions: @@ -514,7 +515,7 @@ A similar grammar written to target Python AST objects: Pegen ------ +===== Pegen is the parser generator used in CPython to produce the final PEG parser used by the interpreter. It is the program that can be used to read the python grammar located in :file:`Grammar/Python.gram` and produce the final C @@ -531,7 +532,7 @@ The source code for Pegen lives at :file:`Tools/peg_generator/pegen` but normall with the parser generator are executed from the main makefile. How to regenerate the parser -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------- Once you have made the changes to the grammar files, to regenerate the ``C`` parser (the one used by the interpreter) just execute: :: @@ -546,7 +547,7 @@ use the Visual Studio project files to regenerate the parser or to execute: :: The generated parser file is located at :file:`Parser/parser.c`. How to regenerate the meta-parser -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- The meta-grammar (the grammar that describes the grammar for the grammar files themselves) is located at :file:`Tools/peg_generator/pegen/metagrammar.gram`. @@ -563,7 +564,7 @@ to regenerate the parser or to execute: :: Grammatical elements and rules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ Pegen has some special grammatical elements and rules: @@ -582,7 +583,7 @@ Pegen has some special grammatical elements and rules: (like any rule in PEG). Tokenization -~~~~~~~~~~~~ +------------ It is common among PEG parser frameworks that the parser does both the parsing and the tokenization, but this does not happen in Pegen. The reason is that the Python language needs a custom tokenizer @@ -604,7 +605,7 @@ How tokens are generated and the rules governing this is completely up to the to and the parser just receives tokens from it. Memoization -~~~~~~~~~~~ +----------- As described previously, to avoid exponential time complexity in the parser, memoization is used. @@ -630,7 +631,7 @@ memoization (check the :file:`Parser/pegen.c` file for more information) but it needs to be manually activated. Automatic variables -~~~~~~~~~~~~~~~~~~~ +------------------- To make writing actions easier, Pegen injects some automatic variables in the namespace available when writing actions. In the C parser, some of these automatic variable names are: @@ -641,7 +642,7 @@ when writing actions. In the C parser, some of these automatic variable names ar location variables are taken from the location information of the current token. Hard and Soft keywords -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- .. note:: In the grammar files, keywords are defined using **single quotes** (e.g. `'class'`) while soft @@ -705,7 +706,7 @@ as well as soft keywords: try to define them in places where there is not a lot of alternatives. Error handling -~~~~~~~~~~~~~~ +-------------- When a pegen-generated parser detects that an exception is raised, it will **automatically stop parsing**, no matter what the current state of the parser @@ -722,7 +723,7 @@ error messages. parser finishes without returning anything. How Syntax errors are reported -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ As described previously in the :ref:`how PEG parsers work section `, PEG parsers don't have a defined concept of where @@ -799,7 +800,7 @@ displayed when the error is reported. will be reported there instead of the ``$`` character. Generating AST objects -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- The output of the C parser used by CPython that is generated by the :file:`Grammar/Python.gram` grammar file is a Python AST object (using C @@ -828,7 +829,7 @@ custom helper in :file:`Parser/action_helpers.c` and expose it in the If the parsing succeeds, the parser **must** return a **valid** AST object. Testing -------- +======= There are three files that contain tests for the grammar and the parser: @@ -843,10 +844,10 @@ Tests for the parser generator itself can be found in the :file:`Lib/test/test_p Debugging generated parsers ---------------------------- +=========================== Making experiments -~~~~~~~~~~~~~~~~~~ +------------------ As the generated C parser is the one used by Python, this means that if something goes wrong when adding some new rules to the grammar you cannot correctly compile and execute Python anymore. This makes it a bit challenging @@ -870,7 +871,7 @@ better understand some complex situations. Verbose mode -~~~~~~~~~~~~ +------------ When Python is compiled in debug mode (by adding ``--with-pydebug`` when running the configure step in Linux or by adding ``-d`` when calling the :file:`PCbuild/build.bat` script in Windows), it is possible to activate a **very** verbose @@ -907,7 +908,7 @@ indicates what alternative within that rule is being attempted. References ----------- +========== .. [1] Ford, Bryan https://pdos.csail.mit.edu/~baford/packrat/thesis/ diff --git a/testing/buildbots.rst b/testing/buildbots.rst index b3454ee8db..e9ccbcab0b 100644 --- a/testing/buildbots.rst +++ b/testing/buildbots.rst @@ -1,6 +1,7 @@ .. _buildbots: -Continuous Integration +====================== +Working with Buildbots ====================== .. highlight:: bash @@ -26,7 +27,7 @@ important that you get acquainted with the way these results are presented, and how various kinds of failures can be explained and diagnosed. In case of trouble ------------------- +================== Please read this page in full. If your questions aren't answered here and you need assistance with the buildbots, a good way to get help is to either: @@ -36,7 +37,7 @@ need assistance with the buildbots, a good way to get help is to either: * contact the release manager of the branch you have issues with. Buildbot failures on Pull Requests ----------------------------------- +================================== The ``bedevere-bot`` on GitHub will put a message on your merged Pull Request if building your commit on a stable buildbot worker fails. Take care to @@ -48,7 +49,7 @@ complete so they are done periodically. This is why it's important for you to be able to check the results yourself, too. Checking results of automatic builds ------------------------------------- +==================================== There are three ways of visualizing recent build results: @@ -89,7 +90,7 @@ branch, it often happens that a single build is scheduled for all these changesets. Stability ---------- +========= A subset of the buildbots are marked "stable". They are taken into account when making a new release. The rule is that all stable builders must be free of @@ -103,7 +104,7 @@ prevent some tests from succeeding (or even terminating at all), but introducing additional failures should generally not be an option. Flags-dependent failures ------------------------- +======================== Sometimes, while you have run the :ref:`whole test suite ` before committing, you may witness unexpected failures on the buildbots. One source @@ -119,7 +120,7 @@ the failing build's tests. For example:: ``-m test``. Ordering-dependent failures ---------------------------- +=========================== Sometimes the failure is even subtler, as it relies on the order in which the tests are run. The buildbots *randomize* test order (by using the ``-r`` @@ -200,7 +201,7 @@ good luck! Transient failures ------------------- +================== While we try to make the test suite as reliable as possible, some tests do not reach a perfect level of reproducibility. Some of them will sometimes @@ -224,7 +225,7 @@ implementation, or by making its parameters - such as a timeout - more robust. Custom builders ---------------- +=============== .. highlight:: console diff --git a/testing/coverage.rst b/testing/coverage.rst index 919b1081b6..2573716eb9 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -1,5 +1,6 @@ .. _coverage: +====================== Increase Test Coverage ====================== @@ -36,7 +37,7 @@ implicit testing by other code that happens to use the module. Common Gotchas -"""""""""""""" +============== Please realize that coverage reports on modules already imported before coverage data starts to be recorded will be wrong. Typically you can tell a module falls @@ -54,7 +55,7 @@ stick with whitebox testing in order to properly exercise the code. Measuring Coverage -"""""""""""""""""" +================== It should be noted that a quirk of running coverage over Python's own stdlib is that certain modules are imported as part of interpreter startup. Those modules @@ -256,7 +257,7 @@ times. Filing the Issue -"""""""""""""""" +================ Once you have increased coverage, you need to create an issue on the `issue tracker`_ and submit a :ref:`pull request `. On the issue set the "Components" to "Test" and "Versions" to the version of Python you @@ -264,7 +265,7 @@ worked on (i.e., the in-development version). Measuring coverage of C code with gcov and lcov -""""""""""""""""""""""""""""""""""""""""""""""" +=============================================== It's also possible to measure the function, line and branch coverage of Python's C code. Right now only GCC with `gcov`_ is supported. In order to diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index e91d22f68c..3593d5a814 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -1,8 +1,8 @@ - .. _buildworker: -Running a buildbot worker -========================= +==================== +New Buildbot Workers +==================== .. highlight:: bash @@ -35,7 +35,7 @@ contribute. Preparing for buildbot worker setup ------------------------------------ +=================================== Since the goal is to build Python from source, the system will need to have everything required to do normal python development: a compiler, a linker, and @@ -53,10 +53,10 @@ the "buildbot worker" step below. Setting up the buildbot worker ------------------------------- +============================== Conventional always-on machines -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------- You need a recent version of the `buildbot `_ software, and you will probably want a separate 'buildbot' user to run the buildbot @@ -195,7 +195,7 @@ idea. Latent workers -^^^^^^^^^^^^^^ +-------------- We also support running `latent workers `_ @@ -242,7 +242,7 @@ buildmaster administrators with the new AMI ID. Buildbot worker operation -------------------------- +========================= Most of the time, running a worker is a "set and forget" operation, depending on the level of involvement you want to have in resolving bugs @@ -273,7 +273,7 @@ to resolve the issue. Required Ports --------------- +============== The worker operates as a *client* to the *buildmaster*. This means that all network connections are *outbound*. This is true also for the network @@ -303,7 +303,7 @@ using either ``localhost`` or ``127.0.0.1``. Required Resources ------------------- +================== Based on the last time we did a `survey `_ on @@ -321,7 +321,7 @@ suite. Security Considerations ------------------------ +======================= We only allow builds to be triggered against commits to the `CPython repository on GitHub `_. diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 20d102a4fd..bed187a0ae 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -1,7 +1,8 @@ .. _runtests: -Running & Writing Tests -======================= +========================= +Running and Writing Tests +========================= .. note:: @@ -11,7 +12,7 @@ Running & Writing Tests on new features not available in earlier versions of Python. Running -------- +======= The shortest, simplest way of running the test suite is the following command from the root directory of your checkout (after you have @@ -96,7 +97,7 @@ above. Unexpected Skips -^^^^^^^^^^^^^^^^ +---------------- Sometimes when running the test suite, you will see "unexpected skips" reported. These represent cases where an entire test module has been @@ -114,7 +115,7 @@ settings on some platforms will disallow some tests) Writing -------- +======= Writing tests for Python is much like writing tests for your own code. Tests need to be thorough, fast, isolated, consistently repeatable, and as simple as @@ -134,7 +135,8 @@ you have to take to make your tests robust and portable. Benchmarks ----------- +========== + Benchmarking is useful to test that a change does not degrade performance. `The Python Benchmark Suite `_ diff --git a/testing/silence-warnings.rst b/testing/silence-warnings.rst index a5f21ed0d3..160d56e24e 100644 --- a/testing/silence-warnings.rst +++ b/testing/silence-warnings.rst @@ -1,5 +1,6 @@ .. _silencewarnings: +==================================== Silence Warnings From the Test Suite ==================================== diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index 9f5fd7c950..7fa390ffac 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -1,6 +1,7 @@ .. _gh-faq: -GitHub issues for BPO users +=========================== +GitHub Issues for BPO Users =========================== Here are some frequently asked questions about how to do things in @@ -11,7 +12,7 @@ and :ref:`triaging` (specifically including :ref:`gh-labels`) as those pages include a lot of introductory material. How to format my comments nicely? ---------------------------------- +================================= There is a wonderful `beginner guide to writing and formatting on GitHub `_. @@ -29,13 +30,13 @@ If you still insist on pasting it in your comment, do it like this:: How to attach files to an issue? --------------------------------- +================================ Drag them into the comment field, wait until the file uploads, and GitHub will automatically put a link to your file in your comment text. How to link to file paths in the repository when writing comments? ------------------------------------------------------------------- +================================================================== Use Markdown links. If you link to the default GitHub path, the file will link to the latest current version on the given branch. @@ -44,13 +45,13 @@ You can get a permanent link to a given revision of a given file by `pressing "y" `_. How to do advanced searches? ----------------------------- +============================ Use the `GitHub search syntax`_ or the interactive `advanced search`_ form that generates search queries for you. Where is the "nosy list"? -------------------------- +========================= Subscribe another person to the issue by tagging them in the comment with ``@username``. @@ -67,7 +68,7 @@ this information during the transfer, we list the previous members of this list in the first message on the migrated issue. How to add issue dependencies? ------------------------------- +============================== Add a checkbox list like this in the issue description:: @@ -81,7 +82,7 @@ closed. More details in the `official GitHub documentation `_. 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 @@ -96,22 +97,22 @@ name in their `bpo`_ profile, we use that. Otherwise, their classic `bpo`_ username is used instead. Where did the "Resolution" field go? ------------------------------------- +==================================== Based on historical data we found it not being used very often. Where did the "Low", "High", and "Critical" priorities go? ----------------------------------------------------------- +========================================================== Based on historical data we found those not being used very often. How to find a random issue? ---------------------------- +=========================== This is not supported by GitHub. Where are regression labels? ----------------------------- +============================ We rarely updated this information and it turned out not to be particularly useful outside of the change log. diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index a848ea3f11..629cb41720 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -1,8 +1,8 @@ .. _tracker: -============== -Issue Tracking -============== +============= +Issue Tracker +============= Using the Issue Tracker diff --git a/triage/labels.rst b/triage/labels.rst index ca6fb6787f..c6e4e3fa70 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -1,5 +1,6 @@ .. _gh-labels: +============= GitHub Labels ============= @@ -9,7 +10,7 @@ only to one. Below is a possibly inexhaustive list, but it should get you going. For a full list, see `here `_. General purpose labels ----------------------- +====================== type-behavior Used for issues/PRs that address unintentional behavior, but do not @@ -43,10 +44,10 @@ spam Used for issues/PRs that don't include enough eggs or bacon. Labels specific to issues -------------------------- +========================= Priority -^^^^^^^^ +-------- release-blocker The highest priority of an issue. If unaddressed, will cause the @@ -59,7 +60,7 @@ deferred-blocker of development. Component -^^^^^^^^^ +--------- library Used for issues involving Python modules in the ``Lib/`` dir. @@ -79,7 +80,7 @@ tests files in the ``Lib/test/`` dir. Other -^^^^^ +----- new Denotes that the issue hasn't been looked at by triagers or core @@ -90,7 +91,7 @@ easy Labels specific to PRs ----------------------- +====================== DO-NOT-MERGE Used on PRs to prevent miss-islington from being able @@ -173,14 +174,14 @@ test-with-buildbots .. _github-pr-labels: GitHub Labels for PRs ---------------------- +===================== An important component of triaging PRs for the CPython repo involves appropriately categorizing them through the usage of labels. For this purpose we're using :ref:`gh-labels`. Applying labels for Issues --------------------------- +========================== The major elements found in an issue report include: @@ -194,7 +195,7 @@ The major elements found in an issue report include: * History Title -''''' +----- A brief description of the issue. Review whether the title is too generic or specifies an incorrect term or library. @@ -202,7 +203,7 @@ specifies an incorrect term or library. IDLE, doc, or asyncio. Type -'''' +---- Describes the type of issue. If an issue does not fit within any specific type, please do not set a type. @@ -234,13 +235,13 @@ specific type, please do not set a type. +----------------+----------------------------------------------------------+ Stage -''''' +----- A needed next action to advance the issue. The *stage* on GitHub issues is determined by presence of a linked PR and whether the issue is still open or closed. It is the PR that holds code review-related labels. Components -'''''''''' +---------- The area or Python library affected by the issue. A single issue can apply multiple component labels. @@ -268,7 +269,7 @@ One or more components may be selected for an issue: +-------------------+------------------------------------------------------+ Versions -'''''''' +-------- The known versions of Python that the issue affects and should be fixed for. Thus if an issue for a new feature is assigned for e.g., Python 3.8 but is not @@ -276,7 +277,7 @@ applied before Python 3.8.0 is released, this label should be updated to say ``python-3.9`` as the version and drop ``python-3.8``. Priority -'''''''' +-------- What is the severity and urgency? +------------------+--------------------------------------------------------+ @@ -301,7 +302,7 @@ tagging them in a comment using ``@username``. If needed, consult the release manager's name. Keywords -'''''''' +-------- Various informational flags about the issue. Multiple values are possible. +---------------+------------------------------------------------------------+ @@ -312,7 +313,7 @@ Various informational flags about the issue. Multiple values are possible. +---------------+------------------------------------------------------------+ Nosy List -''''''''' +--------- A list of people who may be interested in an issue. This used to be a feature of the old issue tracker. On GitHub issues the @@ -328,7 +329,7 @@ decided this issue is not for you, you might click the *🔕 Unsubscribe* button in the sidebar. Assignees -''''''''' +--------- Who is expected to take the next step in resolving the issue. It is acceptable to assign an issue to someone if the issue cannot move @@ -340,7 +341,7 @@ Note that in order to assign an issue to someone, that person **must** be a team member, likely a Triager or a core developer. Dependencies -'''''''''''' +------------ The issue requires the listed issue(s) to be resolved first before it can move forward. This is achieved using checkbox lists in the initial issue description comment. Long story short, if you add this:: @@ -357,12 +358,12 @@ More details in the `official GitHub documentation `_. Superseder -'''''''''' +---------- The issue is a duplicate of the listed issue(s). To make GitHub mark an issue as duplicate, write "Duplicate of #xxxx" in a comment. Status -'''''' +------ +---------------+------------------------------------------------------------+ | Status | Description | @@ -373,13 +374,13 @@ Status +---------------+------------------------------------------------------------+ Linked pull requests -'''''''''''''''''''' +-------------------- A link might be added manually using the cog icon next to this field. Most commonly though, if the PR includes "Fixes #xxx" in its description, the link will be added automatically. Generating Special Links in a Comment -------------------------------------- +===================================== Using the following abbreviations in a comment will automatically generate a link to relevant web pages. diff --git a/triage/triaging.rst b/triage/triaging.rst index 069afb786b..493429fe6d 100644 --- a/triage/triaging.rst +++ b/triage/triaging.rst @@ -1,8 +1,8 @@ .. _triaging: -=================== - Triaging an Issue -=================== +================= +Triaging an Issue +================= This section of the devguide documents the :ref:`issue tracker ` for users and developers. From 7dd5e8c544c4b1615bc3498a13dc862cdd48faba Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Wed, 15 Jun 2022 21:39:55 +0100 Subject: [PATCH 18/21] Update for structure --- documentation/help-documenting.rst | 5 ++--- documentation/markup.rst | 6 +++++- documentation/start-documenting.rst | 8 ++------ documentation/style-guide.rst | 3 +++ testing/new-buildbot-worker.rst | 2 +- 5 files changed, 13 insertions(+), 11 deletions(-) diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index a28b5ff2ca..a70495d1f6 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -14,10 +14,9 @@ This high-level **Helping with Documentation** section provides: * an overview of Python's documentation * how to help with documentation issues * information on proofreading -* guidance on contributing to this Developer's Guide -The next chapter, :ref:`Documenting Python `, gives extensive, -detailed information on how to write documentation and submit changes. +You will find extensive and detailed information on how to write documentation +and submit changes on the :ref:`Documenting Python ` page. Python Documentation diff --git a/documentation/markup.rst b/documentation/markup.rst index 3b08462eac..c657770217 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -6,6 +6,9 @@ reStructuredText Markup .. highlight:: rest +This document describes the custom reStructuredText markup introduced by Sphinx +to support Python documentation and how it should be used. + .. _rst-primer: @@ -190,7 +193,8 @@ A directive is a generic block of explicit markup. Besides roles, it is one of the extension mechanisms of reST, and Sphinx makes heavy use of it. Basically, a directive consists of a name, arguments, options and content. (Keep -this terminology in mind, it is used in the next chapter describing custom +this terminology in mind, it is used in `:ref:`the next section +` describing custom directives.) Looking at this example, :: diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 1648eef945..201c4cd8c8 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -11,10 +11,6 @@ contributed by various authors. The markup used for the Python documentation is `reStructuredText`_, developed by the `docutils`_ project, amended by custom directives and using a toolset named `Sphinx`_ to post-process the HTML output. -This document describes the style guide for our documentation as well as the -custom reStructuredText markup introduced by Sphinx to support Python -documentation and how it should be used. - The documentation in HTML, PDF or EPUB format is generated from text files written using the :ref:`reStructuredText format ` and contained in the :ref:`CPython Git repository `. @@ -43,7 +39,7 @@ The involvement of the community takes many forms, from authoring to bug reports to just plain complaining when the documentation could be more complete or easier to use. -This document is aimed at authors and potential authors of documentation for +This section is aimed at authors and potential authors of documentation for Python. More specifically, it is for people contributing to the standard documentation and developing additional documents using the same tools as the standard documents. This guide will be less useful for authors using the Python @@ -56,7 +52,7 @@ documented here, there's a welcoming place for you among the Python contributors as well. Any time you feel that you can clarify existing documentation or provide documentation that's missing, the existing documentation team will gladly work with you to integrate your text, dealing with the markup for you. -Please don't let the material in this document stand between the documentation +Please don't let the material in this section stand between the documentation and your desire to help out! diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 366d6b23f6..4ebe9f4dc9 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -6,6 +6,9 @@ Style Guide .. highlight:: rest +This document describes the style guide for our documentation. + + Use of whitespace ================= diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index 3593d5a814..a0cdbf3318 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -14,7 +14,7 @@ supported by corporations. Even the corporate sponsored buildbots, however, tend to exist because some individual championed them, made them a reality, and is committed to maintaining them. -Anyone can contribute a buildbot to the fleet. This chapter describes how +Anyone can contribute a buildbot to the fleet. This document describes how to go about setting up a buildbot worker, getting it added, and some hints about buildbot maintenance. From c174ce7449e07280d1c49f1b19069297d396cdb9 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Fri, 17 Jun 2022 11:16:30 +0100 Subject: [PATCH 19/21] Add filenames as targets to all documents --- core-developers/become-core-developer.rst | 1 + core-developers/developer-log.rst | 1 + developer-workflow/c-api.rst | 2 ++ developer-workflow/communication-channels.rst | 1 + developer-workflow/development-cycle.rst | 1 + developer-workflow/extension-modules.rst | 1 + developer-workflow/lang-changes.rst | 1 + developer-workflow/stdlib.rst | 1 + documentation/help-documenting.rst | 1 + documentation/start-documenting.rst | 1 + getting-started/fixing-issues.rst | 1 + getting-started/getting-help.rst | 1 + getting-started/git-boot-camp.rst | 5 +++-- getting-started/pull-request-lifecycle.rst | 1 + getting-started/setup-building.rst | 1 + internals/garbage-collector.rst | 1 + testing/new-buildbot-worker.rst | 1 + testing/run-write-tests.rst | 1 + testing/silence-warnings.rst | 1 + triage/github-bpo-faq.rst | 1 + triage/issue-tracker.rst | 1 + triage/labels.rst | 1 + 22 files changed, 25 insertions(+), 2 deletions(-) diff --git a/core-developers/become-core-developer.rst b/core-developers/become-core-developer.rst index fd762b568f..3c352c037e 100644 --- a/core-developers/become-core-developer.rst +++ b/core-developers/become-core-developer.rst @@ -1,3 +1,4 @@ +.. _become-core-developer: .. _coredev: ============================== diff --git a/core-developers/developer-log.rst b/core-developers/developer-log.rst index 160b7060ec..5a7ff01dde 100644 --- a/core-developers/developer-log.rst +++ b/core-developers/developer-log.rst @@ -1,3 +1,4 @@ +.. _developer-log: .. _developers: Developer Log diff --git a/developer-workflow/c-api.rst b/developer-workflow/c-api.rst index b49b579d04..1d042f70c2 100644 --- a/developer-workflow/c-api.rst +++ b/developer-workflow/c-api.rst @@ -1,3 +1,5 @@ +.. _c-api: + ======================= Changing Python's C API ======================= diff --git a/developer-workflow/communication-channels.rst b/developer-workflow/communication-channels.rst index 4cdbb27600..aaff8eeae7 100644 --- a/developer-workflow/communication-channels.rst +++ b/developer-workflow/communication-channels.rst @@ -1,3 +1,4 @@ +.. _communication-channels: .. _communication: ============================== diff --git a/developer-workflow/development-cycle.rst b/developer-workflow/development-cycle.rst index a0481c8bf0..4ab70670ae 100644 --- a/developer-workflow/development-cycle.rst +++ b/developer-workflow/development-cycle.rst @@ -1,3 +1,4 @@ +.. _development-cycle: .. _devcycle: Development Cycle diff --git a/developer-workflow/extension-modules.rst b/developer-workflow/extension-modules.rst index f69eabefdb..3a5a759a53 100644 --- a/developer-workflow/extension-modules.rst +++ b/developer-workflow/extension-modules.rst @@ -1,3 +1,4 @@ +.. _extension-modules: .. _extensions: ================================== diff --git a/developer-workflow/lang-changes.rst b/developer-workflow/lang-changes.rst index 1a29939f13..108b7b334a 100644 --- a/developer-workflow/lang-changes.rst +++ b/developer-workflow/lang-changes.rst @@ -1,3 +1,4 @@ +.. _lang-changes: .. _langchanges: Changing the Python Language diff --git a/developer-workflow/stdlib.rst b/developer-workflow/stdlib.rst index 99e1eda289..208629bd41 100644 --- a/developer-workflow/stdlib.rst +++ b/developer-workflow/stdlib.rst @@ -1,3 +1,4 @@ +.. _stdlib: .. _stdlibchanges: Adding to the Stdlib diff --git a/documentation/help-documenting.rst b/documentation/help-documenting.rst index a70495d1f6..c8e320ccd8 100644 --- a/documentation/help-documenting.rst +++ b/documentation/help-documenting.rst @@ -1,3 +1,4 @@ +.. _help-documenting: .. _docquality: ========================== diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 201c4cd8c8..8a0db24045 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -1,3 +1,4 @@ +.. _start-documenting: .. _documenting: =============== diff --git a/getting-started/fixing-issues.rst b/getting-started/fixing-issues.rst index 14eb5439b2..70d33dd77f 100644 --- a/getting-started/fixing-issues.rst +++ b/getting-started/fixing-issues.rst @@ -1,3 +1,4 @@ +.. _fixing-issues: .. _fixingissues: ================================= diff --git a/getting-started/getting-help.rst b/getting-started/getting-help.rst index f22c225fd9..60284d955a 100644 --- a/getting-started/getting-help.rst +++ b/getting-started/getting-help.rst @@ -1,3 +1,4 @@ +.. _getting-help: .. _help: Where to Get Help diff --git a/getting-started/git-boot-camp.rst b/getting-started/git-boot-camp.rst index cc745ffa17..259fc1f1f3 100644 --- a/getting-started/git-boot-camp.rst +++ b/getting-started/git-boot-camp.rst @@ -1,10 +1,11 @@ -.. highlight:: console - +.. _git-boot-camp: .. _gitbootcamp: Git Bootcamp and Cheat Sheet ============================ +.. highlight:: console + .. note:: This section provides instructions on common tasks in CPython's diff --git a/getting-started/pull-request-lifecycle.rst b/getting-started/pull-request-lifecycle.rst index 667261e49e..5f2a4262db 100644 --- a/getting-started/pull-request-lifecycle.rst +++ b/getting-started/pull-request-lifecycle.rst @@ -1,3 +1,4 @@ +.. _pull-request-lifecycle: .. _patch: .. _pullrequest: diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst index 1505283920..ba1707a08c 100644 --- a/getting-started/setup-building.rst +++ b/getting-started/setup-building.rst @@ -1,3 +1,4 @@ +.. _setup-building: .. _setup: ================== diff --git a/internals/garbage-collector.rst b/internals/garbage-collector.rst index c058d79332..e79a746837 100644 --- a/internals/garbage-collector.rst +++ b/internals/garbage-collector.rst @@ -1,3 +1,4 @@ +.. _garbage-collector: .. _gc: .. _garbage_collector: diff --git a/testing/new-buildbot-worker.rst b/testing/new-buildbot-worker.rst index a0cdbf3318..53c186ea73 100644 --- a/testing/new-buildbot-worker.rst +++ b/testing/new-buildbot-worker.rst @@ -1,3 +1,4 @@ +.. _new-buildbot-worker: .. _buildworker: ==================== diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index bed187a0ae..fb72bb5694 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -1,3 +1,4 @@ +.. _run-write-tests: .. _runtests: ========================= diff --git a/testing/silence-warnings.rst b/testing/silence-warnings.rst index 160d56e24e..e32da9a9c3 100644 --- a/testing/silence-warnings.rst +++ b/testing/silence-warnings.rst @@ -1,3 +1,4 @@ +.. _silence-warnings: .. _silencewarnings: ==================================== diff --git a/triage/github-bpo-faq.rst b/triage/github-bpo-faq.rst index 7fa390ffac..d69d04fc9c 100644 --- a/triage/github-bpo-faq.rst +++ b/triage/github-bpo-faq.rst @@ -1,3 +1,4 @@ +.. _github-bpo-faq: .. _gh-faq: =========================== diff --git a/triage/issue-tracker.rst b/triage/issue-tracker.rst index 629cb41720..6a0ae22d65 100644 --- a/triage/issue-tracker.rst +++ b/triage/issue-tracker.rst @@ -1,3 +1,4 @@ +.. _issue-tracker: .. _tracker: ============= diff --git a/triage/labels.rst b/triage/labels.rst index c6e4e3fa70..78a5ac9b52 100644 --- a/triage/labels.rst +++ b/triage/labels.rst @@ -1,3 +1,4 @@ +.. _labels: .. _gh-labels: ============= From 1fe880b35f3eb539d2588d9689086e7a521cfab3 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 19 Jun 2022 22:25:23 +0100 Subject: [PATCH 20/21] Update topic table, delete appendix --- appendix.rst | 70 ---------------------------------------------------- index.rst | 45 +++++++++++---------------------- 2 files changed, 14 insertions(+), 101 deletions(-) delete mode 100644 appendix.rst diff --git a/appendix.rst b/appendix.rst deleted file mode 100644 index 296987efae..0000000000 --- a/appendix.rst +++ /dev/null @@ -1,70 +0,0 @@ -Appendix: Topics -================ - -Basics for contributors ------------------------ - -.. note:: **Recommended reading** - - - :doc:`starting/setup` - - :doc:`starting/pullrequest` - -* :doc:`starting/help` -* :doc:`developing/communication` - -Core developers ---------------- - -.. note:: **Recommended reading** - - * :doc:`starting/setup` - * :doc:`starting/pullrequest` - * :doc:`committing/committing` - -* :doc:`committing/coredev` -* :doc:`committing/developers` -* :doc:`committing/motivations` -* :doc:`triaging/experts` - -Development workflow for contributors -------------------------------------- - -* :doc:`developing/devcycle` -* :doc:`starting/pullrequest` -* :doc:`starting/fixingissues` - -Documenting Python and style guide ----------------------------------- - -* :doc:`documenting/docquality` -* :doc:`documenting/documenting` - -Issue tracking and triaging ---------------------------- - -* :doc:`triaging/tracker` -* :doc:`triaging/triaging` -* :doc:`triaging/gh-labels` -* :doc:`triaging/gh-faq` - -Language development in depth ------------------------------ - -* :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:`testing/runtests` -* :doc:`testing/coverage` -* :doc:`testing/silencewarnings` -* :doc:`testing/buildbots` -* :doc:`testing/buildworker` -* :doc:`tooling/coverity` - diff --git a/index.rst b/index.rst index 6355cdeb56..441c55d605 100644 --- a/index.rst +++ b/index.rst @@ -115,36 +115,20 @@ Core developers and contributors alike will find the following guides useful: Guide for contributing to Python: -+------------------------+---------------------+-----------------------+---------------------+ -| New Contributors | Documentarians | Triagers | Core Developers | -+========================+=====================+=======================+=====================+ -| :ref:`setup` | :ref:`docquality` | :ref:`tracker` | :ref:`coredev` | -+------------------------+---------------------+-----------------------+---------------------+ -| :ref:`help` | :ref:`documenting` | :ref:`triaging` | :ref:`developers` | -+------------------------+---------------------+-----------------------+---------------------+ -| :ref:`pullrequest` | :ref:`style-guide` | :ref:`helptriage` | :ref:`committing` | -+------------------------+---------------------+-----------------------+---------------------+ -| :ref:`runtests` | :ref:`rst-primer` | :ref:`experts` | :ref:`devcycle` | -+------------------------+---------------------+-----------------------+---------------------+ -| :ref:`fixingissues` | :ref:`translating` | | :ref:`motivations` | -+------------------------+---------------------+-----------------------+---------------------+ -| :ref:`communication` | | | :ref:`office hour` | -+------------------------+---------------------+-----------------------+---------------------+ -| :ref:`gitbootcamp` | | | | -+------------------------+---------------------+-----------------------+---------------------+ - -Advanced tasks and topics for once you are comfortable: - -* :ref:`silencewarnings` -* Fixing issues found by the :ref:`buildbots ` -* :ref:`coverity` -* Helping out with reviewing `open pull requests`_. - See :ref:`how to review a Pull Request `. -* :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 -sections mentioned in this table. You +======================== =================== ======================= ======================= +Contributors Documentarians Triagers Core Developers +======================== =================== ======================= ======================= +:ref:`setup` :ref:`docquality` :ref:`tracker` :ref:`responsibilities` +:ref:`help` :ref:`documenting` :ref:`triaging` :ref:`developers` +:ref:`pullrequest` :ref:`style-guide` :ref:`helptriage` :ref:`committing` +:ref:`runtests` :ref:`rst-primer` :ref:`experts` :ref:`devcycle` +:ref:`fixingissues` :ref:`translating` :ref:`labels` :ref:`motivations` +:ref:`communication` :ref:`gh-faq` :ref:`office hour` +:ref:`gitbootcamp` :ref:`triage-team` :ref:`experts` +:ref:`devcycle` +======================== =================== ======================= ======================= + +We **recommend** that the documents in this guide be read as needed. You can stop where you feel comfortable and begin contributing immediately without reading and understanding these documents all at once. If you do choose to skip around within the documentation, be aware that it is written assuming preceding @@ -265,7 +249,6 @@ Full Table of Contents internals/index advanced-tools/index versions - appendix .. _Buildbot status: https://www.python.org/dev/buildbot/ .. _Misc directory: https://github.com/python/cpython/tree/main/Misc From 403c00f190c8a0da2b6724e567a9fb05baa7adf8 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sat, 25 Jun 2022 21:02:18 +0100 Subject: [PATCH 21/21] Add redirects --- conf.py | 47 ++++++++++++++++++++++++++++++++++++++++++++++- requirements.txt | 1 + 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 422de53bb6..bd5d850978 100644 --- a/conf.py +++ b/conf.py @@ -29,7 +29,12 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx_copybutton'] +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx_copybutton', + 'sphinxext.rediraffe', +] intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} todo_include_todos = True @@ -226,6 +231,44 @@ # match any anchor that starts with a '/' since this is an invalid HTML anchor '\/.*', ] +rediraffe_redirects = { + "clang.rst": "advanced-tools/clang.rst", + "coverity.rst": "advanced-tools/coverity.rst", + "gdb.rst": "advanced-tools/gdb.rst", + "coredev.rst": "core-developers/become-core-developer.rst", + "committing.rst": "core-developers/committing.rst", + "developers.rst": "core-developers/developer-log.rst", + "experts.rst": "core-developers/experts.rst", + "motivations.rst": "core-developers/motivations.rst", + "c-api.rst": "developer-workflow/c-api.rst", + "communication.rst": "developer-workflow/communication-channels.rst", + "devcycle.rst": "developer-workflow/development-cycle.rst", + "extensions.rst": "developer-workflow/extension-modules.rst", + "grammar.rst": "developer-workflow/grammar.rst", + "langchanges.rst": "developer-workflow/lang-changes.rst", + "porting.rst": "developer-workflow/porting.rst", + "stdlibchanges.rst": "developer-workflow/stdlib.rst", + "docquality.rst": "documentation/help-documenting.rst", + "documenting.rst": "documentation/start-documenting.rst", + "fixingissues.rst": "getting-started/fixing-issues.rst", + "help.rst": "getting-started/getting-help.rst", + "gitbootcamp.rst": "getting-started/git-boot-camp.rst", + "pullrequest.rst": "getting-started/pull-request-lifecycle.rst", + "setup.rst": "getting-started/setup-building.rst", + "compiler.rst": "internals/compiler.rst", + "exploring.rst": "internals/exploring.rst", + "garbage_collector.rst": "internals/garbage-collector.rst", + "parser.rst": "internals/parser.rst", + "buildbots.rst": "testing/buildbots.rst", + "coverage.rst": "testing/coverage.rst", + "buildworker.rst": "testing/new-buildbot-worker.rst", + "runtests.rst": "testing/run-write-tests.rst", + "silencewarnings.rst": "testing/silence-warnings.rst", + "gh-faq.rst": "triage/github-bpo-faq.rst", + "tracker.rst": "triage/issue-tracker.rst", + "gh-labels.rst": "triage/labels.rst", + "triaging.rst": "triage/triaging.rst", +} linkcheck_ignore = [ # The voters repo is private and appears as a 404 @@ -238,6 +281,8 @@ 'https://discuss.python.org/groups/admins', ] + + # Use our custom CSS stylesheet to differentiate us from the official python # docs. def setup(app): diff --git a/requirements.txt b/requirements.txt index c5f1246b3e..a30e3d07c0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,3 +2,4 @@ Sphinx==5.0.2 furo>=2022.6.4 sphinx_copybutton>=0.3.3 sphinx-lint<1 +sphinxext-rediraffe