contrib: restructure Getting Started - Setup and Building into a Workflows section (#1467)

* todo: why duplicate toctree docs here?

* general re-organization

* contrib: replace Get Started with Workflows

* a central links file

This makes it easier to move content around without worrying about where
the links are defined.  It will also be easier to have canonical links
that can be used from multiple places in the guide.

* contrib: restructure Getting Started - Setup and Building into a Workflows section

The Getting Started section has a lot of technical detail.  I thought it
would be better moved to the end, and referenced from the contribution
paths earlier in the guide.  I haven't updated the paths yet.

Also:

- I added a central links.rst that can be included anywhere.
- I omitted the "Editors and tools" section. It doesn't provide any useful information.
- Perhaps the Workflows section could be further categorized.
- The `c_blah_start` and `c_blah_end` comments are only for the temporary inclusions being used to demonstrate the new organization.

* re-order the columns

Author: nedbat

contrib/core-team/index.rst

@@ -5,6 +5,8 @@
    |purpose|
 
 
+.. _c_coreteam:
+
 =========
 Core team
 =========

contrib/get-started/index.rst

@@ -52,7 +52,6 @@ these common sections:
 
 * :ref:`c_intro`
 * :ref:`c_project`
-* :ref:`c_gettingstarted`
 
 Then choose a path based on your type of activity:
 
@@ -68,18 +67,10 @@ major section at the top of each column.]*
    :widths: 10 10 10
    :header-rows: 1
 
-   * - :ref:`Triaging <c_triage>`
-     - :ref:`Documentation <c_docs>`
+   * - :ref:`Documentation <c_docs>`
      - :ref:`Code <c_code>`
+     - :ref:`Triaging <c_triage>`
    * -
-       * :ref:`tracker`
-       * :ref:`triaging`
-       * :ref:`helptriage`
-       * :ref:`experts`
-       * :ref:`labels`
-       * :ref:`gh-faq`
-       * :ref:`triage-team`
-     -
        * :ref:`docquality`
        * :ref:`documenting`
        * :ref:`style-guide`
@@ -95,21 +86,33 @@ major section at the top of each column.]*
        * :ref:`communication`
        * :ref:`gitbootcamp`
        * :ref:`devcycle`
+     -
+       * :ref:`tracker`
+       * :ref:`triaging`
+       * :ref:`helptriage`
+       * :ref:`experts`
+       * :ref:`labels`
+       * :ref:`gh-faq`
+       * :ref:`triage-team`
+
+Core team members will find guidance in the :ref:`c_coreteam` section.
 
+Contents
+========
 
 .. toctree::
    :maxdepth: 3
 
    contrib-plan
    intro/index
    project/index
-   get-started/index
    triage/index
-   code/index
    doc/index
+   code/index
    core-team/index
    user-success
    security
+   workflows/index
 
 
 .. _Python: https://www.python.org/

contrib/index.rst

@@ -0,0 +1,17 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_directory_structure:
+
+===================
+Directory structure
+===================
+
+[This is the :ref:`build_directory_structure` section from the devguide.]
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_directory_structure_start
+   :end-before: c_directory_structure_end

contrib/project/directory-structure.rst

@@ -24,5 +24,6 @@ moving parts, who is involved, how do they interact?]
    governance
    generative-ai.rst
    github
+   directory-structure.rst
    channels
    outreach

contrib/project/index.rst

@@ -0,0 +1,17 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_using_codespaces:
+
+=======================
+Using GitHub Codespaces
+=======================
+
+[This is the :ref:`using-codespaces` section from the devguide.]
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_codespaces_start
+   :end-before: c_codespaces_end

contrib/workflows/codespaces.rst

@@ -0,0 +1,22 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_compiling:
+
+=================
+Compile and build
+=================
+
+.. note::
+   [This is the :ref:`compiling` section from the devguide.  I think this page
+   is too long and could be split by build target, but we can leave that for a
+   later time.]
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_compile_and_build_start
+   :end-before: c_compile_and_build_end
+
+.. include:: ../../links.rst

contrib/workflows/compile.rst

@@ -0,0 +1,19 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_checkout:
+
+===================
+Get the source code
+===================
+
+.. note::
+   [This is the :ref:`checkout` section from the devguide.  We might need to edit
+   it to clarify that some steps are only needed for code contribution.]
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_get_source_code_start
+   :end-before: c_get_source_code_end

contrib/workflows/get-source.rst

@@ -0,0 +1,25 @@
+.. _c_workflows:
+
+=========
+Workflows
+=========
+
+.. important::
+
+   |draft|
+
+   |purpose|
+
+
+This section contains details of workflows needed for all kinds of
+contribution.
+
+.. toctree::
+
+   install-git.rst
+   get-source.rst
+   install-dependencies.rst
+   compile.rst
+   regenerate.rst
+   troubleshooting.rst
+   codespaces.rst

contrib/workflows/index.rst

@@ -0,0 +1,17 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_build-dependencies:
+
+====================
+Install Dependencies
+====================
+
+[This is the :ref:`build-dependencies` section from the devguide.]
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_install_dependencies_start
+   :end-before: c_install_dependencies_end

contrib/workflows/install-dependencies.rst

@@ -0,0 +1,17 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_vcsetup:
+
+===========
+Install Git
+===========
+
+[This is the :ref:`vcsetup` section from the devguide.]
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_install_git_start
+   :end-before: c_install_git_end

contrib/workflows/install-git.rst

@@ -0,0 +1,28 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_regenerating:
+
+===============================
+Regenerating auto-created files
+===============================
+
+.. note::
+   [These are two similar sections from the is the :ref:`setup-building` section from the devguide.]
+
+Regenerate ``configure``
+========================
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_regenerate_configure_start
+   :end-before: c_regenerate_configure_end
+
+Regenerate the ABI dump
+=======================
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_regenerate_abi_start
+   :end-before: c_regenerate_abi_end

contrib/workflows/regenerate.rst

@@ -0,0 +1,17 @@
+.. important::
+
+   |draft|
+
+   |purpose|
+
+.. _c_build_troubleshooting:
+
+===========
+Install Git
+===========
+
+[This is the :ref:`build_troubleshooting` section from the devguide.]
+
+.. include:: ../../getting-started/setup-building.rst
+   :start-after: c_build_troubleshooting_start
+   :end-before: c_build_troubleshooting_end

contrib/workflows/troubleshooting.rst

@@ -1215,6 +1215,9 @@ units as well as normal text:
 Table-of-contents markup
 ------------------------
 
+.. TODO: This is a copy of the Sphinx description of the toctree directive.
+   Why duplicate it here?
+
 Since reST does not have facilities to interconnect several documents, or split
 documents into multiple output files, Sphinx uses a custom directive to add
 relations between the single files the documentation is made of, as well as