Filled some pages from README; added some more empty todo pages

docs/source/index.rst

@@ -10,6 +10,15 @@ GEOS-Chem High Performance
    user-guide/compiling.rst
    user-guide/rundir-init.rst
    user-guide/rundir-config.rst
+   user-guide/running.rst
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Step-by-step Guides
+
+   step-by-step/plotting-output.rst
+   step-by-step/stretched-grid.rst
 
 
 .. toctree::

docs/source/step-by-step/plotting-output.rst

@@ -0,0 +1,6 @@
+
+
+Plotting GCHP output
+====================
+
+todo

docs/source/step-by-step/stretched-grid.rst

@@ -0,0 +1,6 @@
+
+
+Stretched-grid simulations
+==========================
+
+todo

docs/source/user-guide/compiling.rst

@@ -2,4 +2,76 @@
 Compiling GCHP
 ==============
 
-todo
+
+Building with CMake is different than with GNU Make (the way to build GEOS-Chem versions prior to
+13.0). With CMake, there are two steps: (1) a cmake command, and (2) a make command. The cmake
+command is used to set major options, and is often run just once per build directory. Running this
+command with :literal:`-DCMAKE_BUILD_TYPE=Debug` will result in a GCHP build with bounds checking and other
+debug options. Additional compile options, such as :literal:`LUO_WETDEP`, can be appended with :literal:`-D`, e.g.
+:literal:`-DLUO_WETDEP=y`.
+
+Create your build directory
+---------------------------
+
+The build directory will contain all files related to building GCHP with a specific environment and
+set of compiler flags. All source code directories outside of the build directory remain unchanged
+during compilation, unlike in earlier versions of GCHP in which :literal:`*.o` files (for example) were
+scattered throughout the source code tree. You can put your build directory in the root directory of
+Code.GCHP or you can put it anywhere else.
+
+For your very first built we recommend that you build from the source code for simplicity.
+
+.. code-block:: console
+
+   $ cd Code.GCHP
+   $ mkdir build
+
+As you get more advanced, you may wish to create your build directory in your run directory or in a
+directory specific to GCHP version.
+
+Configure CMake
+---------------
+
+The first argument passed to the cmake command must be the relative path to the root GCHP directory.
+For the case of the build directory within source code directory, the root GCHP directory is one
+level up.
+
+.. code-block:: console
+
+   $ cd build
+   $ cmake ..
+
+If you store your build directory in your run directory instead then the relative path would be
+:file:`../CodeDir`, making use of the symbolic link to the source code that is automatically generated when
+creating a run directory.
+
+If the last few lines of output from :program:`cmake` look similar to the following snippet then your build was
+configured successfully.
+
+.. code-block:: none
+
+   ...
+   -- Configuring done
+   -- Generating done
+   -- Build files have been written to: /data10/bindle/Code.GCHP/build
+
+Compile
+-------
+
+The full build does not occur until you run the :program:`make` command.
+
+.. code-block:: console
+
+   $ make -j
+
+
+Recompiling
+-----------
+
+Once the above steps have been performed only the :program:`make` step should be necessary each time you need
+to rebuild the code. The exceptions to this are if you change your environment or your compile
+options. In all cases it should never be necessary to run :command:`make clean`. The :program:`make` command already
+checks all components of the build for changes. If you want to rebuild from scratch because you
+changed environments, simply delete all files from the :file:`build/` directory and recompile. You can also
+create a new build directory (with a different name) and compile from there to preserve your
+previous build.

docs/source/user-guide/downloading.rst

@@ -3,4 +3,21 @@
 Downloading GCHP
 ================
 
-todo
+When cloning GCHP you will get the :literal:`main` branch by default.
+
+.. code-block:: console
+
+   $ git clone https://github.com/geoschem/gchpctm.git Code.GCHP
+   $ cd Code.GCHP
+   $ git submodule update --init --recursive
+
+If you would like a different version of GCHP you can checkout the branch or tag from the top-level
+directory. Beware that you must always then update the submodules again to checkout the compatible
+submodule versions. If you have any unsaved changes in a submdodule, such as local GEOS-Chem
+development, make sure you commit those to a branch prior to updating versions.
+
+.. code-block:: console
+
+   $ cd Code.GCHP
+   $ git checkout tags/13.0.0-alpha.6
+   $ git submodule update --init --recursive

docs/source/user-guide/requirements.rst

@@ -4,9 +4,77 @@ Requirements
 Software requirements
 ---------------------
 
+The following are GCHP's required dependencies:
+
 * Git
 * Fortran compiler (gfortran 8.3 or greater, ifort 18 or greater)
 * CMake (version 3.13 or greater)
 * NetCDF-C, NetCDF-CXX, NetCDF-Fortran
 * MPI (C, C++, and Fortran)
-* ESMF (version 8.0.0 or greater)
+* ESMF (version 8.0.0 or greater)
+
+You must load your environment file prior to building and running GCHP.
+
+.. code-block:: console
+
+   $ source /home/envs/gchpctm_ifort18.0.5_openmpi4.0.1.env
+
+If you don't already have ESMF 8.0.0+, you will need to download and build it. You only need to
+build ESMF once per compiler and MPI configuration (this includes for ALL users on a cluster!). It
+is therefore worth downloading and building somewhere stable and permanent, as almost no users of
+GCHP would be expected to need to modify or rebuild ESMF except when adding a new compiler or MPI.
+Instructions for downloading and building ESMF are available at the GCHP wiki.
+
+It is good practice to store your environment setup in a text file for reuse. Below are a couple
+examples that load libraries and export the necessary environment variables for building and running
+GCHP. Note that library version information is included in the filename for easy reference. Be sure
+to use the same libraries that were used to create the ESMF build install directory stored in
+environment variable :envvar:`ESMF_ROOT`.
+
+**Environment file example 1**
+
+.. code-block:: bash
+
+   # file: gchpctm_ifort18.0.5_openmpi4.0.1.env
+
+   # Start fresh
+   module --force purge
+
+   # Load modules (some include loading other libraries such as netcdf-C and hdf5)
+   module load intel/18.0.5
+   module load openmpi/4.0.1
+   module load netcdf-fortran/4.5.2
+   module load cmake/3.16.1
+
+   # Set environment variables
+   export CC=gcc
+   export CXX=g++
+   export FC=ifort
+
+   # Set location of ESMF
+   export ESMF_ROOT=/n/lab_shared/libraries/ESMF/ESMF_8_0_1/INSTALL_ifort18_openmpi4
+
+**Environment file example 2**
+
+.. code-block:: bash
+
+   # file: gchpctm_gcc7.4_openmpi.rc
+
+   # Start fresh
+   module --force purge
+
+   # Load modules
+   module load gcc-7.4.0
+   spack load cmake
+   spack load openmpi%gcc@7.4.0
+   spack load hdf5%gcc@7.4.0
+   spack load netcdf%gcc@7.4.0
+   spack load netcdf-fortran%gcc@7.4.0
+
+   # Set environment variables
+   export CC=gcc
+   export CXX=g++
+   export FC=gfortran
+
+   # Set location of ESMF
+   export ESMF_ROOT=/n/home/ESMFv8/DEFAULTINSTALLDIR

docs/source/user-guide/rundir-init.rst

@@ -1,3 +1,46 @@
 
 Creating a run directory
 ========================
+
+First, make a high-level directory to contain all the run directories associated with this version
+of GCHP. This should be somewhere with plenty of space, as all run output will be in subdirectories
+of this directory. You can optionally create one or more build directories here for storage and easy
+access to GCHP builds specific to a certain version (see previous section on building GCHP).
+
+.. code-block:: console
+
+   $ mkdir /scratch/testruns/GCHP/13.0.0
+
+Next, enter the :file:`run/` subdirectory in :file:`Code.GCHP`. Do not edit this directory - this is the template for
+all other run directories! Instead, use the script there to create a new run directory, following
+the instructions printed to the screen.
+
+
+.. code-block:: console
+
+   $ cd Code.GCHP
+   $ cd run
+   $ ./createRunDir.sh
+
+For example, to create a standard (full-chemistry) run directory, choose (actual responses in brackets):
+
+* Standard simulation (2)
+* MERRA2 meteorology (2)
+* The directory you just created in step 1 (:file:`/scratch/rundirs/GCHP/13.0.0`)
+* A distinctive run directory name (fullchem_first_test)
+* Use git to track run directory changes (y)
+
+This will create and set up a full-chemistry, MERRA-2, GCHP run directory in
+:file:`/scratch/testruns/GCHP/13.0.0/fullchem_first_test`. Note that these options only affect the run
+directory contents, and NOT the build process - the same GCHP executable is usable for almost all
+simulation types and supported met data options.
+
+Navigate to your new run directory, and set it up for the first run:
+
+.. code-block:: console
+
+   $ cd /scratch/testruns/GCHP/13.0.0/fullchem_first_test
+   $ ./setEnvironment /home/envs/gchpctm_ifort18.0.5_openmpi4.0.1.env # This sets up the gchp.env symlink
+   $ source gchp.env # Set up build environment, if not already done
+   $ cp runScriptSamples/gchp.run . # Set up run script - your system is likely to be different! See also gchp.local.run.
+   $ cp CodeDir/build/bin/geos . # Get the compiled executable

docs/source/user-guide/running.rst

@@ -0,0 +1,10 @@
+
+
+Running GCHP
+============
+
+.. code-block:: console
+
+   $ sbatch gchp.run
+
+For more information about GCHP, see the following resources: GCHP wiki. GCHP issues on GitHub