Lots more structural updates to the docs

geoschem · Dec 16, 2020 · 335b050 · 335b050
1 parent d13c1b7
commit 335b050
Show file tree

Hide file tree

Showing 17 changed files with 65 additions and 30 deletions.
diff --git a/docs/source/bibtex.json b/docs/source/bibtex.json
@@ -7,6 +7,9 @@
             "Eastham_et_al._2018",
             "Zhuang_et_al._2020",
             "Bindle_et_al._2020"
+        ],
+        "stretched-grid": [
+            "Bindle_et_al._2020"
         ]
     }
 }
diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs
diff --git a/docs/source/getting-started/key-references.rst b/docs/source/getting-started/key-references.rst
@@ -1,10 +1,6 @@
 Key References
 ==============
 
-
-Key references
---------------
-
 * GEOS-Chem was first described in :cite:`Bey_et_al._2001`. 
 * HEMCO is described in :cite:`Keller_et_al._2014`.
 * Columnar operators are described in :cite:`Long_et_al._2015`.

diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst
@@ -4,8 +4,8 @@ Quick Start
 ===========
 
 This quickstart guide assumes your environment satisfies :ref:`GCHP's requirements <software_requirements>`. 
-This means you should load a compute environment with programs like :program:`cmake` and :program:`mpirun` before continuing.
-You can find more detailed instructions in the user guide.
+This means you should load a compute environment such that programs like :program:`cmake` and :program:`mpirun`
+are available, before continuing. You can find more detailed instructions in the user guide.
 
 1. Clone GCHP
 -------------
@@ -23,7 +23,20 @@ Checkout the GEOS-Chem version that you want to use:
 
    gcuser:~/GCHP$ git checkout 13.0.0-beta.1
 
-Initialize and update all the submodules.
+.. note::
+   Version 13 is not officially released yet. Until then, the most recent
+   commit to :literal:`main` is the most stable version of GCHP. Therefore,
+   we recommend you checkout :literal:`main`, rather than a version
+   like :literal:`13.0.0-beta.1`. E.g.:
+
+   .. code-block:: console
+
+      $ git checkout main   # recommended until version 13 is officially released
+
+   Once version 13 is released, we will resume recommending users checkout
+   a specific version.
+
+Initialize and update all submodules:
 
 .. code-block:: console
 
@@ -33,7 +46,7 @@ Initialize and update all the submodules.
 -------------------------
 
 Navigate to the :file:`run/` subdirectory. 
-Create a run directory by running :file:`./createRunDir.sh` and following the prompts:
+Create a run directory by running :file:`./createRunDir.sh` and answering the prompts:
 
 .. code-block:: console
 
@@ -44,7 +57,7 @@ Create a run directory by running :file:`./createRunDir.sh` and following the pr
 -----------------------
 
 Create a build directory and :command:`cd` into it. 
-A good name for this directory is :file:`build/`, and a good place to put it is in the 
+A good name for this directory is :file:`build/`, and a good place for it is in the 
 top-level of the source code:
 
 .. code-block:: console

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -40,15 +40,15 @@ problems.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Supplemental Guides
+   :caption: Supplement
 
-   step-by-step/rundir-config.rst
-   step-by-step/config-files.rst
-   step-by-step/spack.rst
-   step-by-step/containers.rst
-   step-by-step/plotting-output.rst
+   supplement/rundir-config.rst
+   supplement/config-files.rst
+   supplement/spack.rst
+   supplement/containers.rst
+   supplement/plotting-output.rst
    stretched-grid.rst
-   step-by-step/satellite-overpass.rst
+   supplement/satellite-overpass.rst
 
 .. toctree::
    :maxdepth: 1
@@ -62,7 +62,7 @@ problems.
 
    reference/SUPPORT.md
    reference/CONTRIBUTING.md
-   reference/glossary.rst
    geos-chem-shared-docs/editing_these_docs.rst
    reference/git-submodules.rst
+   reference/glossary.rst
    reference/versioning.rst
diff --git a/docs/source/reference/git-submodules.rst b/docs/source/reference/git-submodules.rst
@@ -1,6 +1,6 @@
 
 
-Git submodules
+Git Submodules
 ==============
 
 

diff --git a/docs/source/stretched-grid.rst b/docs/source/stretched-grid.rst
@@ -1,8 +1,12 @@
 
 
-Stretched-grid simulations
+Stretched-Grid Simulations
 ==========================
 
+.. note::
+   Stretched-grid simulations are described in :cite:`Bindle_et_al._2020`. The paper also discusses things
+   you should consider, and offers guidance for choosing appropriate stretching parameters.
+
 A stretched-grid is a cubed-sphere grid that is "stretched" to enhance its resolution in a region.
 To set up a stretched-grid simulation you need to do two things:
 
@@ -148,4 +152,5 @@ configuration files.
 
 .. code-block:: console
 
-   $ ./runConfig.sh
+   $ ./runConfig.sh
+
diff --git a/docs/source/step-by-step/config-files.rst → docs/source/supplement/config-files.rst b/docs/source/step-by-step/config-files.rst → docs/source/supplement/config-files.rst
@@ -1,4 +1,4 @@
-Configuration files
+Configuration Files
 ===================
 
 GCHP is controlled using a set of resource configuration files that are included in the GCHP run directory, most of which are denoted by suffix :file:`.rc`. 

diff --git a/docs/source/step-by-step/containers.rst → docs/source/supplement/containers.rst b/docs/source/step-by-step/containers.rst → docs/source/supplement/containers.rst
@@ -1,4 +1,4 @@
-Using GCHP containers
+Using GCHP Containers
 =====================
 
 Containers are an effective method of packaging and delivering GCHP's source code and requisite libraries.

diff --git a/docs/source/step-by-step/plotting-output.rst → docs/source/supplement/plotting-output.rst b/docs/source/step-by-step/plotting-output.rst → docs/source/supplement/plotting-output.rst
@@ -1,6 +1,6 @@
 
 
-Plotting GCHP output
+Plotting GCHP Output
 ====================
 
 todo
diff --git a/docs/source/step-by-step/rundir-config.rst → docs/source/supplement/rundir-config.rst b/docs/source/step-by-step/rundir-config.rst → docs/source/supplement/rundir-config.rst
@@ -1,6 +1,6 @@
 
 
-Run directory configuration
+Run Directory Configuration
 ===========================
 
 All GCHP run directories have default simulation-specific run-time settings that are set when you create a run directory. 

diff --git a/...ource/step-by-step/satellite-overpass.rst → .../source/supplement/satellite-overpass.rst b/...ource/step-by-step/satellite-overpass.rst → .../source/supplement/satellite-overpass.rst
@@ -1,6 +1,6 @@
 
 
-Output along a track
+Output Along a Track
 ====================
 
 HISTORY collections can define a :literal:`track_file` that specifies a 1D timeseries of coordinates

diff --git a/docs/source/step-by-step/spack.rst → docs/source/supplement/spack.rst b/docs/source/step-by-step/spack.rst → docs/source/supplement/spack.rst
@@ -1,7 +1,7 @@
 
 .. _installing_with_spack:
 
-Installing dependencies with Spack
+Installing Dependencies with Spack
 ==================================
 
 

diff --git a/docs/source/tutorials/stretched-grid.rst b/docs/source/tutorials/stretched-grid.rst
@@ -1,4 +1,4 @@
-Stretched-grid simulation: Eastern US 
+Stretched-Grid Simulation: Eastern US 
 =====================================
 
 This tutorial walks you through setting up and running a stretched-grid simulation

diff --git a/docs/source/user-guide/downloading.rst b/docs/source/user-guide/downloading.rst
@@ -25,5 +25,18 @@ Checkout the version that you want to work with, and update your submodules:
 
 .. code-block:: console
 
-   gcuser:~/Code.GCHP$ git checkout 13.0.0
+   gcuser:~/Code.GCHP$ git checkout 13.0.0-beta.1
    gcuser:~/Code.GCHP$ git submodule update --init --recursive
+
+.. note::
+   Version 13 is not officially released yet. Until then, the most recent
+   commit to :literal:`main` is the most stable version of GCHP. Therefore,
+   we recommend you checkout :literal:`main`, rather than a version
+   like :literal:`13.0.0-beta.1`. E.g.:
+
+   .. code-block:: console
+
+      $ git checkout main   # recommended until version 13 is officially released
+
+   Once version 13 is released, we will resume recommending users checkout
+   a specific version.
diff --git a/docs/source/user-guide/rundir-init.rst b/docs/source/user-guide/rundir-init.rst
@@ -1,5 +1,5 @@
 
-Creating a run directory
+Creating a Run Directory
 ========================
 
 GCHP run directories are created from within the source code.

diff --git a/docs/source/user-guide/running.rst b/docs/source/user-guide/running.rst
@@ -4,6 +4,11 @@
 Running GCHP
 ============
 
+
+.. note::
+   Another useful resource for instructions on running GCHP is our `YouTube tutorial <https://www.youtube.com/watch?v=K6frcfCjpds>`_.
+
+
 This page presents the basic information needed to run GCHP as well as how to verify a successful run and reuse a run directory. 
 A pre-run checklist is included at the end to help prevent run errors. 
 The GCHP "standard" simulation run directory is configured for a 1-hr simulation at c24 resolution and is a good first test case to check that GCHP runs on your system.