From 5ccee3046b8542fa54e9d9f45544083193b39a37 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sat, 19 Oct 2024 08:30:50 -0400 Subject: [PATCH 1/3] mark the plan page as an aside to the reviewer --- contrib/contrib-plan.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/contrib/contrib-plan.rst b/contrib/contrib-plan.rst index be35c1a8d..36a171bf1 100644 --- a/contrib/contrib-plan.rst +++ b/contrib/contrib-plan.rst @@ -1,8 +1,8 @@ .. _contrib-plan: -================================ -Plan for the Contributor's Guide -================================ +================================== +[Plan for the Contributor's Guide] +================================== .. important:: From 3bd13a34c5e8e28a1dbde398959e28d2e24cb1f9 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 23 Oct 2024 07:01:32 -0400 Subject: [PATCH 2/3] link to the internals section from the contrib mention of it --- contrib/code/index.rst | 2 +- internals/index.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/contrib/code/index.rst b/contrib/code/index.rst index 4839d1bf0..50bf2c31e 100644 --- a/contrib/code/index.rst +++ b/contrib/code/index.rst @@ -13,7 +13,7 @@ Code contributions [We'll include code-focused content from the :ref:`main devguide page `: Quick reference, Quick links, Proposing changes, and so on.] -[The existing "CPython's internals" section of the devguide will be fully +[The existing :ref:`internals` section of the devguide will be fully migrated into the Python repo.] diff --git a/internals/index.rst b/internals/index.rst index 999e427b2..05723f482 100644 --- a/internals/index.rst +++ b/internals/index.rst @@ -1,3 +1,5 @@ +.. _internals: + =================== CPython's internals =================== From 667f2e75e7ed051102d1bfb2e09952f55c28a429 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 23 Oct 2024 07:29:31 -0400 Subject: [PATCH 3/3] contrib: populate the docs section Also added a pull-request-lifecycle page to the Code section. --- contrib/code/index.rst | 1 + contrib/code/pull-request-lifecycle.rst | 21 +++++++++++++++++++++ contrib/doc/devguide.rst | 12 ++++++++++++ contrib/doc/help-documenting.rst | 12 ++++++++++++ contrib/doc/index.rst | 23 ++++++++++++++++------- contrib/doc/markup.rst | 12 ++++++++++++ contrib/doc/pull-request-lifecycle.rst | 21 +++++++++++++++++++++ contrib/doc/start-documenting.rst | 12 ++++++++++++ contrib/doc/style-guide.rst | 12 ++++++++++++ contrib/doc/translating.rst | 12 ++++++++++++ 10 files changed, 131 insertions(+), 7 deletions(-) create mode 100644 contrib/code/pull-request-lifecycle.rst create mode 100644 contrib/doc/devguide.rst create mode 100644 contrib/doc/help-documenting.rst create mode 100644 contrib/doc/markup.rst create mode 100644 contrib/doc/pull-request-lifecycle.rst create mode 100644 contrib/doc/start-documenting.rst create mode 100644 contrib/doc/style-guide.rst create mode 100644 contrib/doc/translating.rst diff --git a/contrib/code/index.rst b/contrib/code/index.rst index 50bf2c31e..5f1e4c0f6 100644 --- a/contrib/code/index.rst +++ b/contrib/code/index.rst @@ -22,6 +22,7 @@ migrated into the Python repo.] setup git + pull-request-lifecycle developer-workflow testing development-tools diff --git a/contrib/code/pull-request-lifecycle.rst b/contrib/code/pull-request-lifecycle.rst new file mode 100644 index 000000000..30c0fd590 --- /dev/null +++ b/contrib/code/pull-request-lifecycle.rst @@ -0,0 +1,21 @@ +.. _code-pull-request-lifecycle: + +====================== +Pull request lifecycle +====================== + +.. important:: + + |draft| + + |purpose| + + +[Details of pull requests for code contributions. The existing +:ref:`pull-request-lifecycle` page is long and includes many details. +Some only apply to code contributions, but many are common to all +contributions. Should we keep a common page, with extra steps here, or +should this page have all of the details even if they are duplicated +elsewhere?] + +[See :ref:`docs-pull-request-lifecycle` for the documentation half of this conundrum.] diff --git a/contrib/doc/devguide.rst b/contrib/doc/devguide.rst new file mode 100644 index 000000000..2c83e5200 --- /dev/null +++ b/contrib/doc/devguide.rst @@ -0,0 +1,12 @@ +================================== +Helping with the Developer's Guide +================================== + +.. important:: + + |draft| + + |purpose| + + +[This is the existing :ref:`devguide` page from the devguide.] diff --git a/contrib/doc/help-documenting.rst b/contrib/doc/help-documenting.rst new file mode 100644 index 000000000..befb4b246 --- /dev/null +++ b/contrib/doc/help-documenting.rst @@ -0,0 +1,12 @@ +========================== +Helping with documentation +========================== + +.. important:: + + |draft| + + |purpose| + + +[This is the existing :ref:`help-documenting` page from the devguide.] diff --git a/contrib/doc/index.rst b/contrib/doc/index.rst index e5d60e42f..224469d2c 100644 --- a/contrib/doc/index.rst +++ b/contrib/doc/index.rst @@ -9,10 +9,19 @@ Documentation contributions |purpose| -* Lifecycle of a docs pull request -* (pull in Documentation sections from devguide) -* Rst/Sphinx bootcamp -* Editorial Style Guide -* Translation - - How to add a new language - - Tools and workflow +[The main page for documentation contributors.] + +[We'll include docs-focused content from the :ref:`main devguide page `: Quick +reference, Quick links, and so on.] + + +.. toctree:: + :maxdepth: 5 + + start-documenting + help-documenting + style-guide + markup + pull-request-lifecycle + translating + devguide diff --git a/contrib/doc/markup.rst b/contrib/doc/markup.rst new file mode 100644 index 000000000..96b9faad5 --- /dev/null +++ b/contrib/doc/markup.rst @@ -0,0 +1,12 @@ +======================= +reStructuredText markup +======================= + +.. important:: + + |draft| + + |purpose| + + +[This is the existing :ref:`markup` page from the devguide.] diff --git a/contrib/doc/pull-request-lifecycle.rst b/contrib/doc/pull-request-lifecycle.rst new file mode 100644 index 000000000..a62e63728 --- /dev/null +++ b/contrib/doc/pull-request-lifecycle.rst @@ -0,0 +1,21 @@ +.. _docs-pull-request-lifecycle: + +====================== +Pull request lifecycle +====================== + +.. important:: + + |draft| + + |purpose| + + +[Details of pull requests for documentation contributions. The existing +:ref:`pull-request-lifecycle` page is long and includes many details. +Some only apply to code contributions, but many are common to all +contributions. Should we keep a common page, with documentation tweaks here, or +should this page have only the documentation details even if they are duplicated +elsewhere?] + +[See :ref:`code-pull-request-lifecycle` for the code half of this conundrum.] diff --git a/contrib/doc/start-documenting.rst b/contrib/doc/start-documenting.rst new file mode 100644 index 000000000..c5cf96161 --- /dev/null +++ b/contrib/doc/start-documenting.rst @@ -0,0 +1,12 @@ +=============== +Getting started +=============== + +.. important:: + + |draft| + + |purpose| + + +[This is the existing documentation :ref:`start-documenting` page from the devguide.] diff --git a/contrib/doc/style-guide.rst b/contrib/doc/style-guide.rst new file mode 100644 index 000000000..87762f3e0 --- /dev/null +++ b/contrib/doc/style-guide.rst @@ -0,0 +1,12 @@ +=========== +Style guide +=========== + +.. important:: + + |draft| + + |purpose| + + +[This is the existing documentation :ref:`style-guide` page from the devguide.] diff --git a/contrib/doc/translating.rst b/contrib/doc/translating.rst new file mode 100644 index 000000000..baface2f0 --- /dev/null +++ b/contrib/doc/translating.rst @@ -0,0 +1,12 @@ +=========== +Translating +=========== + +.. important:: + + |draft| + + |purpose| + + +[This is the existing :ref:`translating` page from the devguide.]