diff --git a/_static/devguide_overrides.css b/_static/devguide_overrides.css index 9237445d2f..8e2c7c6fca 100644 --- a/_static/devguide_overrides.css +++ b/_static/devguide_overrides.css @@ -94,3 +94,9 @@ font-size: var(--font-size--small--2); padding: .1em .2em; } + +/* Table cells should always top-align */ + +table.docutils td { + vertical-align: top; +} diff --git a/contrib/code/index.rst b/contrib/code/index.rst index 5f1e4c0f67..7680950663 100644 --- a/contrib/code/index.rst +++ b/contrib/code/index.rst @@ -1,3 +1,5 @@ +.. _c_code: + ================== Code contributions ================== diff --git a/contrib/project/core-team/committing.rst b/contrib/core-team/committing.rst similarity index 78% rename from contrib/project/core-team/committing.rst rename to contrib/core-team/committing.rst index 569f6e27de..59cf7c1af2 100644 --- a/contrib/project/core-team/committing.rst +++ b/contrib/core-team/committing.rst @@ -8,4 +8,4 @@ [This is the existing core developers :ref:`committing` page from the devguide. We'll adjust "core developer" to "core team" where appropriate.] -.. include:: ../../../core-developers/committing.rst +.. include:: ../../core-developers/committing.rst diff --git a/contrib/project/core-team/developer-log.rst b/contrib/core-team/developer-log.rst similarity index 77% rename from contrib/project/core-team/developer-log.rst rename to contrib/core-team/developer-log.rst index 00d7803035..473cd3c6c6 100644 --- a/contrib/project/core-team/developer-log.rst +++ b/contrib/core-team/developer-log.rst @@ -8,4 +8,4 @@ [This is the existing core developers :ref:`developer-log` page from the devguide. We'll adjust "core developer" to "core team" where appropriate.] -.. include:: ../../../core-developers/developer-log.rst +.. include:: ../../core-developers/developer-log.rst diff --git a/contrib/project/core-team/experts.rst b/contrib/core-team/experts.rst similarity index 78% rename from contrib/project/core-team/experts.rst rename to contrib/core-team/experts.rst index 358fdd17fc..7f2a103cd5 100644 --- a/contrib/project/core-team/experts.rst +++ b/contrib/core-team/experts.rst @@ -8,4 +8,4 @@ [This is the existing core developers :ref:`experts` page from the devguide. We'll adjust "core developer" to "core team" where appropriate.] -.. include:: ../../../core-developers/experts.rst +.. include:: ../../core-developers/experts.rst diff --git a/contrib/project/core-team/index.rst b/contrib/core-team/index.rst similarity index 100% rename from contrib/project/core-team/index.rst rename to contrib/core-team/index.rst diff --git a/contrib/project/core-team/join-team.rst b/contrib/core-team/join-team.rst similarity index 83% rename from contrib/project/core-team/join-team.rst rename to contrib/core-team/join-team.rst index 1905c92a95..0c893ae08d 100644 --- a/contrib/project/core-team/join-team.rst +++ b/contrib/core-team/join-team.rst @@ -12,5 +12,5 @@ adjust "core developer" to "core team" where appropriate.] How to join the core team ========================= -.. include:: ../../../core-developers/become-core-developer.rst +.. include:: ../../core-developers/become-core-developer.rst :start-line: 7 diff --git a/contrib/project/core-team/motivations.rst b/contrib/core-team/motivations.rst similarity index 77% rename from contrib/project/core-team/motivations.rst rename to contrib/core-team/motivations.rst index 79af3ccfdf..c9e0281b6f 100644 --- a/contrib/project/core-team/motivations.rst +++ b/contrib/core-team/motivations.rst @@ -8,4 +8,4 @@ [This is the existing core developers :ref:`motivations` page from the devguide. We'll adjust "core developer" to "core team" where appropriate.] -.. include:: ../../../core-developers/motivations.rst +.. include:: ../../core-developers/motivations.rst diff --git a/contrib/project/core-team/responsibilities.rst b/contrib/core-team/responsibilities.rst similarity index 76% rename from contrib/project/core-team/responsibilities.rst rename to contrib/core-team/responsibilities.rst index ca974b35cd..a3de329561 100644 --- a/contrib/project/core-team/responsibilities.rst +++ b/contrib/core-team/responsibilities.rst @@ -8,4 +8,4 @@ [This is the existing core developers :ref:`responsibilities` page from the devguide. We'll adjust "core developer" to "core team" where appropriate.] -.. include:: ../../../core-developers/responsibilities.rst +.. include:: ../../core-developers/responsibilities.rst diff --git a/contrib/doc/index.rst b/contrib/doc/index.rst index 224469d2c2..dc8ec93074 100644 --- a/contrib/doc/index.rst +++ b/contrib/doc/index.rst @@ -1,3 +1,5 @@ +.. _c_docs: + =========================== Documentation contributions =========================== diff --git a/contrib/get-started/index.rst b/contrib/get-started/index.rst index 84c5afd707..70e61b1b1b 100644 --- a/contrib/get-started/index.rst +++ b/contrib/get-started/index.rst @@ -1,3 +1,5 @@ +.. _c_gettingstarted: + =============== Getting started =============== diff --git a/contrib/index.rst b/contrib/index.rst index 1c169ffbeb..b3ef0d992a 100644 --- a/contrib/index.rst +++ b/contrib/index.rst @@ -1,7 +1,18 @@ +.. _c_root: + ================================== Python Contributor's Guide (draft) ================================== +.. raw:: html + + + + .. important:: |draft| @@ -9,20 +20,85 @@ Python Contributor's Guide (draft) |purpose| -This guide is a comprehensive resource for contributing to Python. +[Open question: how to divide content between this Introduction and the +:ref:`introduction `?] + +This guide is a comprehensive resource for :ref:`contributing ` +to Python_ -- for both new and experienced contributors. It is :ref:`maintained +` by the same community that maintains Python. We welcome your +contributions to Python! + +We encourage everyone to contribute to Python. This guide should have +everything you need to get started and be productive. If you still have +questions after reviewing the material in this guide, the `Core Python +Mentorship`_ group is available to help you through the process. + +There are a number of ways to contribute including code, documentation, and +triaging issues. We've organized this guide to provide specifics based on the +type of activity you'll be engaged in. + + +Using this guide +================ -.. note:: - This is a draft of a new organization for the devguide, turning it into a - Contributor's Guide. +We recommend reading this guide as needed. You can stop where you feel +comfortable and begin contributing immediately without reading and +understanding everything. If you do choose to skip around this guide, be aware +that it is written assuming preceding sections have been read so you may need +to backtrack to fill in missing concepts and terminology. -[Much of the devguide home page will be here. The Quick Start will be updated -to distinguish code vs documentation contributions, and moved to those -sections. Other changes will be made to explain the different types of -contribution and how to navigate the guide for your own type.] +No matter what kind of contribution you'll be making, you should start with +these common sections: + +* :ref:`c_intro` +* :ref:`c_project` +* :ref:`c_gettingstarted` + +Then choose a path based on your type of activity: + +*[The original table on the devguide home had a fourth column for Core +Developers. That made the table wider and more confusing. I don't think core +team members need a quick intro path since they will have been through the +devguide before.]* + +*[I haven't adjusted the links in the table yet other than to add a link to the +major section at the top of each column.]* + +.. list-table:: + :widths: 10 10 10 + :header-rows: 1 + + * - :ref:`Triaging ` + - :ref:`Documentation ` + - :ref:`Code ` + * - + * :ref:`tracker` + * :ref:`triaging` + * :ref:`helptriage` + * :ref:`experts` + * :ref:`labels` + * :ref:`gh-faq` + * :ref:`triage-team` + - + * :ref:`docquality` + * :ref:`documenting` + * :ref:`style-guide` + * :ref:`rst-primer` + * :ref:`translating` + * :ref:`devguide` + - + * :ref:`setup` + * :ref:`help` + * :ref:`pullrequest` + * :ref:`runtests` + * :ref:`fixingissues` + * :ref:`communication` + * :ref:`gitbootcamp` + * :ref:`devcycle` .. toctree:: - :maxdepth: 2 + :maxdepth: 3 contrib-plan intro/index @@ -31,6 +107,10 @@ contribution and how to navigate the guide for your own type.] triage/index code/index doc/index + core-team/index user-success security - outreach + + +.. _Python: https://www.python.org/ +.. _Core Python Mentorship: https://www.python.org/dev/core-mentorship/ diff --git a/contrib/intro/index.rst b/contrib/intro/index.rst index 0a733adaac..c5ba303dfd 100644 --- a/contrib/intro/index.rst +++ b/contrib/intro/index.rst @@ -1,3 +1,5 @@ +.. _c_intro: + ============ Introduction ============ @@ -10,10 +12,27 @@ Introduction +[Open question: how to divide content between this Introduction and the +:ref:`home page `?] Welcome! -Healthy Collaboration +New to open source? +=================== + +Python is an open source project, with culture and techniques from the broader +open source world. You might find it helpful to read about open source in +general. A number of individuals from the Python community have contributed to +a series of excellent guides at `Open Source Guides +`_. + +Anyone will find the following guides useful: + +* `How to Contribute to Open Source `_ +* `Building Welcoming Communities `_ + + +Healthy collaboration ===================== [Importance of healthy inclusive collaboration] @@ -22,13 +41,13 @@ Healthy Collaboration [We respect the individual skills people bring to the project and strive to create and maintain a culture of inclusion.] -About this Guide +About this guide ================ -Types of Contribution +Types of contribution ===================== [Pathways for contributors] -Helping with this Guide +Helping with this guide ======================= diff --git a/contrib/project/generative-ai.rst b/contrib/project/generative-ai.rst new file mode 100644 index 0000000000..6cb5b62ffc --- /dev/null +++ b/contrib/project/generative-ai.rst @@ -0,0 +1,10 @@ +.. important:: + + |draft| + + |purpose| + + +[This is the existing :ref:`generative-ai` page from the devguide.] + +.. include:: ../../getting-started/generative-ai.rst diff --git a/contrib/project/index.rst b/contrib/project/index.rst index 082be327e8..5d26b15aab 100644 --- a/contrib/project/index.rst +++ b/contrib/project/index.rst @@ -1,3 +1,5 @@ +.. _c_project: + =================== The CPython project =================== @@ -19,7 +21,8 @@ moving parts, who is involved, how do they interact?] conduct roles - core-team/index governance + generative-ai.rst github channels + outreach diff --git a/contrib/outreach.rst b/contrib/project/outreach.rst similarity index 100% rename from contrib/outreach.rst rename to contrib/project/outreach.rst diff --git a/contrib/triage/index.rst b/contrib/triage/index.rst index 9257978a6a..0a547d9d77 100644 --- a/contrib/triage/index.rst +++ b/contrib/triage/index.rst @@ -1,3 +1,5 @@ +.. _c_triage: + =================== Issues and triaging ===================