Lots of structural updates to the documentation

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

Hide file tree

Showing 18 changed files with 142 additions and 418 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+## Contributing Guidelines
+
+Thank you for looking into contributing to GEOS-Chem! GEOS-Chem is a grass-roots model that relies on 
+contributions from community members like you. Whether you're new to GEOS-Chem 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 GCHP source code, to track issues, user questions, and feature requests, and to accept pull requests: [https://github.com/geoschem/GCHP](https://github.com/geoschem/GCHP). Please help out as you can in response to issues and user questions.
+
+We use ReadTheDocs to host the GCHP user documentation: [https://gchp.readthedocs.io](https://gchp.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). If your change affects multiple
+submodules, submit a pull request for each submodule with changes, and link to these submodule pull requests in your main pull request.
+
+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 GEOS-Chem 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/GCHP/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".
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -0,0 +1,21 @@
+## Support Guidelines
+
+GEOS-Chem 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/GCHP/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/GCHP/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".
diff --git a/docs/source/bibtex.json b/docs/source/bibtex.json
@@ -0,0 +1,12 @@
+{
+    "cited": {
+        "getting-started/key-references": [
+            "Bey_et_al._2001",
+            "Keller_et_al._2014",
+            "Long_et_al._2015",
+            "Eastham_et_al._2018",
+            "Zhuang_et_al._2020",
+            "Bindle_et_al._2020"
+        ]
+    }
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,10 +33,44 @@
 # ones.
 extensions = [
     "sphinx_rtd_theme",   
+    "sphinxcontrib.bibtex",
+    "recommonmark",
 ]
+bibtex_default_style = 'gcrefstyle'
+
+from pybtex.style.formatting.unsrt import Style as UnsrtStyle
+from pybtex.style.names.lastfirst import NameStyle as LastFirst
+from pybtex.style.template import join, words, optional, sentence
+from pybtex.style.labels import BaseLabelStyle
+
+class GCLabelStyle(BaseLabelStyle):
+    def format_labels(self, sorted_entries):
+        for entry in sorted_entries:
+            yield entry.key.replace("_", " ").replace("et al.", "et al.,")
+
+class GCRefStyle(UnsrtStyle):
+    default_name_style = LastFirst
+    default_sort_style = None
+    default_label_style = GCLabelStyle
+
+    def __init__(self):
+       super().__init__()
+       self.abbreviate_names = True
+      #  self.label_style = KeyLabelStyle()
+      #  self.format_labels = self.label_style.format_labels
+
+    def format_web_refs(self, e):
+       return sentence[ optional[ self.format_doi(e) ], ]
+
+from pybtex.plugin import register_plugin
+register_plugin('pybtex.style.formatting', 'gcrefstyle', GCRefStyle)
+
+
+bibtex_bibliography_header = ".. rubric:: References"
+bibtex_footbibliography_header = bibtex_bibliography_header
+
+bibtex_bibfiles = ['geos-chem-shared-docs/geos-chem.bib']
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/docs/source/geos-chem-shared-docs b/docs/source/geos-chem-shared-docs
diff --git a/docs/source/getting-started/gentle-intro.rst b/docs/source/getting-started/gentle-intro.rst
diff --git a/docs/source/getting-started/getting-help.rst b/docs/source/getting-started/getting-help.rst
diff --git a/docs/source/getting-started/key-references.rst b/docs/source/getting-started/key-references.rst
@@ -0,0 +1,15 @@
+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`.
+* GEOS-Chem High Performance (GCHP) is described in :cite:`Eastham_et_al._2018`.
+* GCHP execution on the cloud and MPI considerations are described in :cite:`Zhuang_et_al._2020`.
+* Grid-stretching is described in :cite:`Bindle_et_al._2020`.
+
+.. bibliography::
diff --git a/docs/source/getting-started/quick-start.rst b/docs/source/getting-started/quick-start.rst
@@ -1,6 +1,6 @@
 
 
-Quick start
+Quick Start
 ===========
 
 This quickstart guide assumes your environment satisfies :ref:`GCHP's requirements <software_requirements>`. 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -2,16 +2,19 @@ GEOS-Chem High Performance
 ==========================
 
 .. important:: This is a prerelease of the GEOS-Chem High Performance user guide.
-   Everything here is still a work in progress.
-
+   These pages are the most up-to-date and accurate instructions for GCHP, but they
+   are still a work in progress. 
+
+   Contributions (e.g., suggestions, edits, revisions) would be greatly appreciated. See
+   :ref:`editing this guide <editing_this_user_guide>` and our :doc:`contributing guidelines <reference/CONTRIBUTING>`. 
+   If you find a something hard to understand---let us know!
 
 The `GEOS--Chem model <http://acmg.seas.harvard.edu/geos/>`_ is a global 3-D model of atmospheric
 composition driven by assimilated meteorological observations from the Goddard Earth Observing
 System (GEOS) of the `NASA Global Modeling and Assimilation Office <http://gmao.gsfc.nasa.gov/>`_.
 It is applied by `research groups around the world
 <http://acmg.seas.harvard.edu/geos/geos_people.html>`_ to a wide range of atmospheric composition
-problems, Central management and support of the model is provided by the `Atmospheric Chemistry
-Modeling Group at Harvard University <http://acmg.seas.harvard.edu/index.html>`_.
+problems.
 
 * `GEOS-Chem Overview <http://acmg.seas.harvard.edu/geos/geos_overview.html>`_
 * `Narrative description of GEOS-Chem <http://acmg.seas.harvard.edu/geos/geos_chem_narrative.html>`_
@@ -20,10 +23,10 @@ Modeling Group at Harvard University <http://acmg.seas.harvard.edu/index.html>`_
    :maxdepth: 1
    :caption: Getting Started
 
+
    getting-started/quick-start.rst
    getting-started/requirements.rst
-..    getting-started/gentle-intro.rst
-..    getting-started/getting-help.rst
+   getting-started/key-references.rst
 
 .. toctree::
    :maxdepth: 2
@@ -36,8 +39,8 @@ Modeling Group at Harvard University <http://acmg.seas.harvard.edu/index.html>`_
 
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Step-by-step Guides
+   :maxdepth: 1
+   :caption: Supplemental Guides
 
    step-by-step/rundir-config.rst
    step-by-step/config-files.rst
@@ -48,7 +51,7 @@ Modeling Group at Harvard University <http://acmg.seas.harvard.edu/index.html>`_
    step-by-step/satellite-overpass.rst
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Tutorials
 
    tutorials/stretched-grid.rst
@@ -57,9 +60,9 @@ Modeling Group at Harvard University <http://acmg.seas.harvard.edu/index.html>`_
    :maxdepth: 1
    :caption: Help & Reference
 
+   reference/SUPPORT.md
+   reference/CONTRIBUTING.md
    reference/glossary.rst
-   reference/contributing.rst
-   reference/FAQ.rst
    geos-chem-shared-docs/editing_these_docs.rst
    reference/git-submodules.rst
    reference/versioning.rst
diff --git a/docs/source/reference/CONTRIBUTING.md b/docs/source/reference/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../../CONTRIBUTING.md
diff --git a/docs/source/reference/FAQ.rst b/docs/source/reference/FAQ.rst
diff --git a/docs/source/reference/SUPPORT.md b/docs/source/reference/SUPPORT.md
@@ -0,0 +1 @@
+../../../SUPPORT.md
diff --git a/docs/source/reference/contributing.rst b/docs/source/reference/contributing.rst
diff --git a/docs/source/step-by-step/rundir-config.rst b/docs/source/step-by-step/rundir-config.rst
@@ -52,11 +52,11 @@ Please get very familiar with the options in :file:`runConfig.sh` and be conscie
 You generally will not need to know more about the GCHP configuration files beyond what is listed on this page. 
 However, for a comprehensive description of all configuration files used by GCHP see the last section of this user manual.
 
+---------------------------------------------------------------------------------------------------
+
 Common options
 --------------
 
----------------------------------------------------------------------------------------------------
-
 Compute configuration
 ^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/source/stretched-grid.rst b/docs/source/stretched-grid.rst
@@ -35,7 +35,7 @@ covers the refion that you want to refine.
 .. note::
 
    The interactive figure above can be a bit fiddly. Refresh the page if the view gets messed up.
-   If the figure above is not showing up properly, please :ref:`open an issue <open_an_issue>`.
+   If the figure above is not showing up properly, please :doc:`open an issue <reference/SUPPORT>`.
 
 Next you need to choose a cubed-sphere size. The cubed-sphere size must be an even integer (e.g.,
 C90, C92, C94, etc.). Remeber that the resolution of the target face is enhanced by approximately the

diff --git a/docs/source/user-guide/compiling.rst b/docs/source/user-guide/compiling.rst
@@ -91,7 +91,7 @@ as you need to configure your desired settings.
    The :literal:`.` argument is important. It is the path to your build directory which
    is :literal:`.` here.
 
-GCHP has no required build settings. You can find the complete list of GCHP's build settings `here <Build options for GCHP>`_.
+GCHP has no required build settings. You can find the complete list of :ref:`GCHP's build settings here <gchp_build_options>`.
 The most frequently used build setting is :literal:`RUNDIR` which lets you specify one or more run directories
 to install GCHP to. Here, "install" refers to copying the compiled executable, and some supplemental files
 with build settings, to your run directories.
@@ -206,7 +206,7 @@ RRTMG
     Switch to enable/disable the RRTMG component.
 
 OMP
-   Switch to enable/disable OpenMP multithreading. As is standard in CMake (see `here <https://cmake.org/cmake/help/latest/command/if.html>`_) valid values are :literal:`ON`, :literal:`YES`, :literal:`Y`, :literal:`TRUE`, or :literal:`1` (case-insensitive) and valid
+   Switch to enable/disable OpenMP multithreading. As is standard in CMake (see `if documentation <https://cmake.org/cmake/help/latest/command/if.html>`_) valid values are :literal:`ON`, :literal:`YES`, :literal:`Y`, :literal:`TRUE`, or :literal:`1` (case-insensitive) and valid
    false values are their opposites.
 
 INSTALLCOPY