From facd6f83e63de3ad0e51e04219ed526ca79d5a25 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Wed, 23 Oct 2024 15:32:23 -0400 Subject: [PATCH] Populate the docs section of the new contrib structure (#1454) * mark the plan page as an aside to the reviewer * link to the internals section from the contrib mention of it * contrib: populate the docs section Also added a pull-request-lifecycle page to the Code section. --- contrib/code/index.rst | 3 ++- contrib/code/pull-request-lifecycle.rst | 21 +++++++++++++++++++++ contrib/contrib-plan.rst | 6 +++--- 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 ++++++++++++ internals/index.rst | 2 ++ 12 files changed, 137 insertions(+), 11 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 4839d1bf01..5f1e4c0f67 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.] @@ -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 0000000000..30c0fd5903 --- /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/contrib-plan.rst b/contrib/contrib-plan.rst index be35c1a8db..36a171bf14 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:: diff --git a/contrib/doc/devguide.rst b/contrib/doc/devguide.rst new file mode 100644 index 0000000000..2c83e52003 --- /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 0000000000..befb4b2461 --- /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 e5d60e42f4..224469d2c2 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 0000000000..96b9faad5e --- /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 0000000000..a62e637283 --- /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 0000000000..c5cf96161b --- /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 0000000000..87762f3e03 --- /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 0000000000..baface2f0d --- /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.] diff --git a/internals/index.rst b/internals/index.rst index 999e427b2d..05723f4824 100644 --- a/internals/index.rst +++ b/internals/index.rst @@ -1,3 +1,5 @@ +.. _internals: + =================== CPython's internals ===================