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

contrib/core-team/index.rst

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

contrib/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/project/directory-structure.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/index.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/workflows/codespaces.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/compile.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/get-source.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/index.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/install-dependencies.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-git.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/regenerate.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/troubleshooting.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

documentation/markup.rst

@@ -1219,6 +1219,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