Contrib guide: more restructuring (#1461)

* contrib guide: more restructuring * review comment fixes * table tweaks
python · Nov 3, 2024 · e0bc90a · e0bc90a
1 parent 1d6cc2f
commit e0bc90a
Show file tree

Hide file tree

Showing 17 changed files with 147 additions and 21 deletions.
diff --git 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
@@ -1,3 +1,5 @@
+.. _c_code:
+
 ==================
 Code contributions
 ==================

diff --git a/contrib/project/core-team/committing.rst → contrib/core-team/committing.rst b/contrib/project/core-team/committing.rst → 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 → contrib/core-team/developer-log.rst b/contrib/project/core-team/developer-log.rst → 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 → contrib/core-team/experts.rst b/contrib/project/core-team/experts.rst → 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 → contrib/core-team/index.rst b/contrib/project/core-team/index.rst → contrib/core-team/index.rst
diff --git a/contrib/project/core-team/join-team.rst → contrib/core-team/join-team.rst b/contrib/project/core-team/join-team.rst → 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 → contrib/core-team/motivations.rst b/contrib/project/core-team/motivations.rst → 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/...ib/project/core-team/responsibilities.rst → contrib/core-team/responsibilities.rst b/...ib/project/core-team/responsibilities.rst → 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
@@ -1,3 +1,5 @@
+.. _c_docs:
+
 ===========================
 Documentation contributions
 ===========================

diff --git 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
@@ -1,28 +1,104 @@
+.. _c_root:
+
 ==================================
 Python Contributor's Guide (draft)
 ==================================
 
+.. raw:: html
+
+    <script>
+    document.addEventListener('DOMContentLoaded', function() {
+      activateTab(getOS());
+    });
+    </script>
+
+
 .. important::
 
    |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 <c_intro>`?]
+
+This guide is a comprehensive resource for :ref:`contributing <contributing>`
+to Python_ -- for both new and experienced contributors. It is :ref:`maintained
+<devguide>` 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 <c_triage>`
+     - :ref:`Documentation <c_docs>`
+     - :ref:`Code <c_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
@@ -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 <c_root>`?]
 
 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
+<https://opensource.guide/>`_.
+
+Anyone will find the following guides useful:
+
+* `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`_
+* `Building Welcoming Communities <https://opensource.guide/building-community/>`_
+
+
+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
@@ -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
@@ -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 → contrib/project/outreach.rst b/contrib/outreach.rst → contrib/project/outreach.rst
diff --git a/contrib/triage/index.rst b/contrib/triage/index.rst
@@ -1,3 +1,5 @@
+.. _c_triage:
+
 ===================
 Issues and triaging
 ===================