Update documentation for HEMCO 3.0.0

Signed-off-by: Melissa Sulprizio <[email protected]>

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+## Contributing Guidelines
+
+Thank you for looking into contributing to HEMCO! HEMCO is a grass-roots model that relies on 
+contributions from community members like you. Whether you're new to HEMCO or a longtime user, 
+you're a valued member of the community, and we want you to feel empowered to contribute.
+
+#### We use GitHub and ReadTheDocs
+We use GitHub to host the HEMCO source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/HEMCO](https://github.com/geoschem/HEMCO). Please help out as you can in response to issues and user questions.
+
+We use ReadTheDocs to host the HEMCO user documentation: [https://hemco.readthedocs.io](https://hemco.readthedocs.io).
+
+#### How to submit changes
+We use [GitHub Flow](https://guides.github.com/introduction/flow/index.html), so all changes happen through pull requests. This
+workflow is described here: [GitHub Flow](https://guides.github.com/introduction/flow/index.html).
+
+As the author you are responsible for:
+- Testing your changes
+- Updating the user documentation (if applicable)
+- Supporting issues and questions related to your changes in the near-term
+
+#### Coding conventions
+The HEMCO codebase dates back several decades and includes contributions from many people and multiple organizations.
+Therefore, some inconsistent conventions are inevitable, but we ask that you do your best to be consistent with nearby
+code.
+
+#### How to request an enhancement
+We accept feature requests through issues on GitHub. To request a new feature, [open a new issue](https://github.com/geoschem/HEMCO/issues/new/choose) and select the feature request template. Please include all the information that migth be relevant, including the motivation
+for the feature.
+
+#### How to report a bug
+Please see "Support Guidelines".
+
+#### Where can I ask for help?
+Please see "Support Guidelines".

README.md

@@ -2,7 +2,21 @@
 
 # README for the HEMCO source code repository
 
-This repository (https://github.com/geoschem/HEMCO) contains the Harmonized Emissions Component (HEMCO) source code. HEMCO is a software component for computing (atmospheric) emissions from different sources, regions, and species on a user-defined grid. It can combine, overlay, and update a set of data inventories ('base emissions') and scale factors, as specified by the user through the HEMCO configuration file. Emissions that depend on environmental variables and non-linear  parameterizations are calculated in separate HEMCO extensions. HEMCO can be run in standalone mode or coupled to an atmospheric model. A more detailed description of HEMCO is given in Keller et al. (2014).
+This repository (https://github.com/geoschem/HEMCO) contains the Harmonized Emissions Component 
+(HEMCO) source code. HEMCO is a software component for computing (atmospheric) emissions from
+different sources, regions, and species on a user-defined grid. It can combine, overlay, and
+update a set of data inventories ('base emissions') and scale factors, as specified by the user
+through the HEMCO configuration file. Emissions that depend on environmental variables and 
+non-linear  parameterizations are calculated in separate HEMCO extensions. HEMCO can be run 
+in standalone mode or coupled to an atmospheric model. A more detailed description of HEMCO 
+is given in Keller et al. (2014).
+
+## CI statuses
+
+Pipeline | Status
+:---|:---
+Build Matrix (main) | [![Build Status](https://dev.azure.com/geoschem/hemco/_apis/build/status/Build%20Matrix?branchName=main)](https://dev.azure.com/geoschem/hemco/_build/latest?definitionId=7&branchName=main)
+
 
 ## Documentation
 
@@ -11,26 +25,20 @@ This repository (https://github.com/geoschem/HEMCO) contains the Harmonized Emis
 C. A. Keller, M. S. Long, R. M. Yantosca, A. M. Da Silva, S. Pawson, D. J. Jacob, *HEMCO v1.0: a versatile,
 ESMF-compliant component for calculation emissions in atmospheric models*, <u>Geosci. Model Dev.</u>, **7**, 1409-1417, 2014.
 
-### Website
-
-  * [HEMCO wiki page](http://wiki.seas.harvard.edu/geos-chem/index.php/HEMCO)
-
 ### Online user's manual
 
-  * [The HEMCO User's Guide](http://wiki.seas.harvard.edu/geos-chem/index.php/The_HEMCO_User%27s_Guide)
+  * [The HEMCO User's Guide](http://hemco.readthedocs.io)
 
 
 ## Support
-
-You are encouraged use the Github issue tracker attached to this repository to report  bugs or technical issues with the HEMCO code.
-
-You are also invited to direct HEMCO support requests to the GEOS-Chem Support Team at [email protected].
+We encourage GEOS-Chem users to use [the Github issue tracker attached to this repository](https://github.com/geoschem/HEMCO/issues/new/choose) to report bugs or technical issues with the HEMCO code.
 
 ## License
 
-HEMCO is distributed under the MIT license. Please see the license documents LICENSE.txt and AUTHORS.txt in the root folder.
+HEMCO is distributed under the MIT license. Please see the license documents LICENSE.txt and
+AUTHORS.txt in the root folder.
 
 
-26 Sep 2019
+08 Jan 2021
 GEOS-Chem Support Team
 [email protected]

SUPPORT.md

@@ -0,0 +1,21 @@
+## Support Guidelines
+
+HEMCO support is maintained by the GEOS-Chem Support Team (GCST). 
+The GCST members are based at Harvard University and Washington University in St. Louis.
+
+We track bugs, user questions, and feature requests through GitHub issues. 
+Please help out as you can in response to issues and user questions.
+
+
+#### How to report a bug
+We use GitHub to track issues. To report a bug, [open a new issue](https://github.com/geoschem/HEMCO/issues/new/choose). Please include
+all the information that might be relevant, including instructions for reproducing the bug.  
+
+#### Where can I ask for help?
+We use GitHub issues to support user questions. To ask a question, [open a new issue](https://github.com/geoschem/HEMCO/issues/new/choose) and select the question template. 
+
+#### How to submit changes
+Please see "Contributing Guidelines".
+
+#### How to request an enhancement
+Please see "Contributing Guidelines".

docs/requirements.txt

@@ -0,0 +1,5 @@
+# Requirements for building the GCHP documentation
+sphinx
+sphinx_rtd_theme
+sphinxcontrib-bibtex 
+recommonmark

docs/source/_static/theme_overrides.css

@@ -0,0 +1,10 @@
+/* override table width restrictions */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.wy-table-responsive {
+    margin-bottom: 24px;
+    max-width: 100%;
+    overflow: visible;
+}

docs/source/conf.py

@@ -56,6 +56,11 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',  # overrides for wide tables in RTD theme
+        ],
+    }
 
 # Display GEOS-Chem logo
 html_favicon = 'geos-chem-shared-docs/_static/favicon.png'

docs/source/getting-started/key-references.rst

@@ -0,0 +1,7 @@
+Key References
+==============
+
+* GEOS-Chem was first described in :cite:`Bey_et_al._2001`. 
+* HEMCO is described in :cite:`Keller_et_al._2014`.
+
+.. bibliography::

docs/source/getting-started/quick-start.rst

@@ -1,6 +1,129 @@
 
 
-Quick start
+Quick Start
 ===========
 
-todo
+This quickstart guide assumes your environment satisfies :ref:`HEMCO's requirements <software_requirements>`. 
+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 HEMCO
+--------------
+
+Download the source code:
+
+.. code-block:: console
+
+   $ git clone https://github.com/geoschem/HEMCO.git ~/HEMCO
+   $ cd ~/HEMCO
+
+Checkout the HEMCO version that you want to use:
+
+.. code-block:: console
+
+   $ git checkout 3.0.0-rc.0
+
+2. Create a run directory
+-------------------------
+
+Navigate to the :file:`run/` subdirectory. 
+Create a run directory by running :file:`./createRunDir.sh` and answering the prompts:
+
+.. code-block:: console
+
+   $ cd run/
+   $ ./createRunDir.sh
+
+3. Configure your build
+-----------------------
+
+Create a build directory and :command:`cd` into it. 
+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
+
+   $ mkdir ~/HEMCO/build
+   $ cd ~/HEMCO/build
+
+Initialize your build directory by running :program:`cmake` and passing it the path to your source code:
+
+.. code-block:: console
+
+   $ cmake ~/HEMCO
+
+Now you can configure :ref:`build options <HEMCO_build_options>`. 
+These are persistent settings that are saved to your build directory.
+A common build option is :literal:`-DRUNDIR`. 
+This option lets you specify one or more run directories that HEMCO is "installed" to when you do :command:`make install`. 
+Configure your build so it installs HEMCO to the run directory you created in Step 2:
+
+.. code-block:: console
+
+   $ cmake . -DRUNDIR="/path/to/rundir"
+
+.. note::
+   The :literal:`.` in the :program:`cmake` command above is important. It tells CMake that your 
+   current working directory (i.e., :literal:`.`) is your build directory.
+
+4. Compile and install
+----------------------
+
+Compile HEMCO:
+
+.. code-block:: console
+
+   $ make -j
+
+Next, install the compiled executable to your run directory (or directories):
+
+.. code-block:: console
+
+   $ make install
+
+This copies :file:`build/bin/hemco_standalone` and supplemental files to your run directory. 
+
+.. note::
+   You can update build settings at any time:
+
+   1. Navigate to your build directory.
+   2. Update your build settings with :program:`cmake`. See 
+   3. Recompile with :command:`make -j`. Note that the build system automatically figures out what (if any) files
+      need to be recompiled.
+   4. Install the rebuilt executable with :command:`make install`.
+
+
+5. Configure your run directory
+-------------------------------
+
+Now, navigate to your run directory:
+
+.. code-block:: console
+
+   $ cd path/to/rundir
+
+Simulation settings are configured in the :file:`.rc` files. The main configuration file
+is :file:`HEMCO_sa_Config.rc`. The start end end time for your simulation can be modified in
+:file:`HEMCO_sa_Time.rc`. The horizontal grid for your simulation can be modified in
+:file:`HEMCO_sa_Grid.rc`. Emissions settings can be changed in the `HEMCO_Config.rc` file
+that has been copied from another model (e.g. GEOS-Chem).
+
+6. Run HEMCO
+------------
+
+HEMCO can be run interactively from within your run directory by typing:
+
+.. code-block:: console
+
+   $ ./hemco_standalone
+
+You may also submit your HEMCO simulation as a batch job to a scheduler.  A sample run script
+:file:`runHEMCO.sh` is included in your run directory. To submit a HEMCO simulation using
+SLURM:
+
+.. code-block:: console
+
+   $ sbatch runHEMCO.sh
+
+Those are the basics of using HEMCO! See the user guide, step-by-step guides, and reference pages
+for more detailed instructions.