contrib guide: more restructuring

nedbat · nedbat · commit be7cd9fa4b94 · 2024-10-31T09:18:46.000-04:00
diff --git a/contrib/code/index.rst b/contrib/code/index.rst
@@ -1,3 +1,5 @@
+.. _c_code:
+
 ==================
 Code contributions
 ==================
diff --git a/contrib/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/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/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/core-team/index.rst b/contrib/core-team/index.rst
diff --git a/contrib/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/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/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
@@ -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,116 @@
+.. _c_root:
+
 ==================================
 Python Contributor's Guide (draft)
 ==================================
 
+.. raw:: html
+
+    <script>
+    document.addEventListener('DOMContentLoaded', function() {
+      activateTab(getOS());
+    });
+    </script>
+    <style>
+      table.docutils td { vertical-align: top; }
+    </style>
+
+
 .. 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
+================
+
+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.
 
-.. note::
-   This is a draft of a new organization for the devguide, turning it into a
-   Contributor's Guide.
+No matter what kind of contribution you'll be making, you should start with
+these common sections:
 
-[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.]
+* :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
+
+   * - Triaging
+     - Documentation
+     - Code
+   * -
+       :ref:`c_triage`
+
+       * :ref:`tracker`
+       * :ref:`triaging`
+       * :ref:`helptriage`
+       * :ref:`experts`
+       * :ref:`labels`
+       * :ref:`gh-faq`
+       * :ref:`triage-team`
+     -
+       :ref:`c_docs`
+
+       * :ref:`docquality`
+       * :ref:`documenting`
+       * :ref:`style-guide`
+       * :ref:`rst-primer`
+       * :ref:`translating`
+       * :ref:`devguide`
+     -
+       :ref:`c_code`
+
+       * :ref:`setup`
+       * :ref:`help`
+       * :ref:`pullrequest`
+       * :ref:`runtests`
+       * :ref:`fixingissues`
+       * :ref:`communication`
+       * :ref:`gitbootcamp`
+       * :ref:`devcycle`
+
+[The contents had been listed below here. It was very long, and I don't think
+it was helpful.  The left sidebar has the contents.]
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :hidden:
 
    contrib-plan
    intro/index
@@ -31,6 +119,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,9 +12,26 @@ Introduction
 
 
 
+[Open question: how to divide content between this Introduction and the
+:ref:`home page <c_root>`?]
 
 Welcome!
 
+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
 =====================
 
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/project/outreach.rst b/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
 ===================

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _c_code:`
	`2`	`+`
`1`	`3`	`==================`
`2`	`4`	`Code contributions`
`3`	`5`	`==================`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _c_docs:`
	`2`	`+`
`1`	`3`	`===========================`
`2`	`4`	`Documentation contributions`
`3`	`5`	`===========================`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+.. _c_gettingstarted:`
	`2`	`+`
`1`	`3`	`===============`
`2`	`4`	`Getting started`
`3`	`5`	`===============`