3 add rate constant descriptions and configuration formats

.github/workflows/gh-pages.yml

@@ -0,0 +1,76 @@
+name: Docs
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+    branches:
+      - main
+
+permissions:
+    contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+
+      - name: Debugging information
+        run: |
+          echo "github.ref:" ${{github.ref}}
+          echo "github.event_name:" ${{github.event_name}}
+          echo "github.head_ref:" ${{github.head_ref}}
+          echo "github.base_ref:" ${{github.base_ref}}
+          set -x
+          git rev-parse --abbrev-ref HEAD
+          git branch
+          git branch -a
+          git remote -v
+          python -V
+          pip list --not-required
+          pip list
+
+      - name: Setup gh-pages folder
+        run: |
+          set -x
+          git fetch
+          ( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
+          rm -rf _gh-pages/.git/
+
+      - name: Install dependencies
+        run: |
+          pip install -r docs/requirements.txt
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+          ls -l
+          ls -l build/html
+          cp -r build/html/* ../_gh-pages/
+
+      # Add the .nojekyll file
+      - name: nojekyll
+        if: ${{ github.event_name == 'push' }}
+        run: |
+          touch _gh-pages/.nojekyll
+
+      - name: Debugging information
+        run: |
+          ls -la _gh-pages/
+
+      # Deploy
+      # https://github.com/peaceiris/actions-gh-pages
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _gh-pages/
+          force_orphan: true

docs/requirements.txt

@@ -1,4 +1,6 @@
 pydata-sphinx-theme
 sphinx
 sphinx-design
-sphinx-tabs
+sphinx-tabs
+sphinxcontrib-bibtex
+sphinxemoji

docs/source/_static/css/custom.css

@@ -0,0 +1,24 @@
+.download-div {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-around;
+  margin-bottom: 1rem;
+}
+
+.download-button {
+  display: inline-block;
+  padding: 10px 20px;
+  background-color: #3498db;
+  color: white;
+  border: none;
+  border-radius: 5px;
+  text-align: center;
+  text-decoration: none;
+  font-size: 16px;
+  cursor: pointer;
+  transition: background-color 0.3s;
+}
+
+.download-button:hover {
+  background-color: #2980b9;
+}

docs/source/bibliography.rst

@@ -0,0 +1,6 @@
+############
+Bibliography
+############
+
+.. bibliography::
+   :all:

docs/source/conf.py

@@ -1,30 +1,40 @@
+import datetime
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-project = 'CAMP Configuration'
-copyright = '2023, OpenAtmos'
+project = 'Mechanism Configuration'
+current_year = datetime.datetime.now().year
+copyright = f"2022-{current_year}, OpenAtmos"
 author = 'OpenAtmos'
-release = '0.0.0'
+version = '1.0.0'
+release = version
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-  'sphinx_design',
-  'sphinx_tabs.tabs',
+    'sphinx_design',
+    'sphinx_tabs.tabs',
+    'sphinxcontrib.bibtex',
+    'sphinxemoji.sphinxemoji',
 ]
 
 templates_path = ['_templates']
 exclude_patterns = []
 
-
+bibtex_bibfiles = ['references.bib']
+suppress_warnings = ["bibtex.missing_field"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'pydata_sphinx_theme'
-html_static_path = ['_static']
+html_static_path = ['_static']
+html_css_files = [
+    'css/custom.css',
+]

docs/source/examples/index.rst

@@ -13,18 +13,30 @@ Chapman
 Top Level Config
 ----------------
 
+.. raw:: html
+
+    <div class="download-div">
+    <a href="../_static/examples/yaml/chapman/chapman.zip" download>
+       <button class="download-button">Download yaml ZIP</button>
+    </a>
+    <a href="../_static/examples/json/chapman/chapman.zip" download>
+       <button class="download-button">Download json ZIP</button>
+    </a>
+    </div>
+
+
 .. tabs::
 
     .. tab:: YAML
 
-        .. literalinclude:: ../../../examples/yaml/chapman/config.yaml
+        .. literalinclude:: ../_static/examples/yaml/chapman/config.yaml
             :language: yaml
 
     .. tab:: JSON
 
-        .. literalinclude:: ../../../examples/json/chapman/config.json
+        .. literalinclude:: ../_static/examples/json/chapman/config.json
             :language: json
-
+    
 
 Reactions
 ---------
@@ -33,12 +45,12 @@ Reactions
 
     .. tab:: YAML
 
-        .. literalinclude:: ../../../examples/yaml/chapman/reactions.yaml
+        .. literalinclude:: ../_static/examples/yaml/chapman/reactions.yaml
             :language: yaml
 
     .. tab:: JSON
 
-        .. literalinclude:: ../../../examples/json/chapman/reactions.json
+        .. literalinclude:: ../_static/examples/json/chapman/reactions.json
             :language: json
 
 Species
@@ -48,10 +60,10 @@ Species
 
     .. tab:: YAML
 
-        .. literalinclude:: ../../../examples/yaml/chapman/species.yaml
+        .. literalinclude:: ../_static/examples/yaml/chapman/species.yaml
             :language: yaml
 
     .. tab:: JSON
 
-        .. literalinclude:: ../../../examples/json/chapman/species.json
+        .. literalinclude:: ../_static/examples/json/chapman/species.json
             :language: json

docs/source/index.rst

@@ -1,9 +1,9 @@
-.. CAMP Configuration documentation master file, created by
+.. OpenAtmos Mechanism Configuration documentation master file, created by
    sphinx-quickstart on Fri Jul 21 21:05:33 2023.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-.. camp configuration documentation HTML titles
+.. open atmos mechanism configuration documentation HTML titles
 ..
 .. # (over and under) for module headings
 .. = for sections
@@ -12,16 +12,19 @@
 .. ~ for subsubsubsections
 .. " for paragraphs
 
-##############################################
-Welcome to CAMP Configuration's documentation!
-##############################################
+.. |project_version| replace:: 1.0.0
+
+###############################################################
+Welcome to the OpenAtmos Mechanism Configuration documentation!
+###############################################################
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    aerosol_phases/index
    aerosol_representations/index
+   bibliography
    chemical_species/index
    examples/index
    mechanisms/index

docs/source/reactions/aqueous_equilibrium.rst

@@ -0,0 +1,76 @@
+Aqueous-Phase Equilibrium
+=========================
+
+Aqueous equilibrium reactions are calculated as forward and reverse reactions.
+The reverse rate constant must be provided as part of the input data, and the forward rate constant is calculated using the provided 
+reverse rate constant and an equilibrium constant of the following format:
+
+.. math::
+
+   A e^{C \left(\frac{1}{T} - \frac{1}{298}\right)}
+
+where:
+
+- :math:`A` is the pre-exponential factor (:math:`\mathrm{s}^{-1}`),
+- :math:`C` is a constant,
+- :math:`T` is the temperature :math:`(\mathrm{K})`.
+
+Input data for aqueous equilibrium equations should take the form:
+
+.. tabs::
+
+    .. tab:: YAML
+
+        .. code-block:: yaml
+
+            type: AQUEOUS_EQUILIBRIUM
+            A: 123.45
+            C: 123.45
+            k_reverse: 123.45
+            phase: "my aqueous phase"
+            time unit: MIN
+            aqueous-phase water: "H2O_aq"
+            ion pair: "spec3-spec4"
+            reactants:
+              spec1: {}
+              spec2:
+                qty: 2
+            # ... (other reactants)
+            products:
+              spec3: {}
+              spec4:
+                qty: 0.65
+            # ... (other products)
+
+    .. tab:: JSON
+
+        .. code-block:: json
+
+            {
+                "type" : "AQUEOUS_EQUILIBRIUM",
+                "A" : 123.45,
+                "C" : 123.45,
+                "k_reverse" : 123.45,
+                "phase" : "my aqueous phase",
+                "time unit" : "MIN",
+                "aqueous-phase water" : "H2O_aq",
+                "ion pair" : "spec3-spec4",
+                "reactants" : {
+                    "spec1" : {},
+                    "spec2" : { "qty" : 2 },
+                },
+                "products" : {
+                    "spec3" : {},
+                    "spec4" : { "qty" : 0.65 },
+                }
+            }
+
+The key-value pairs ``reactants`` and ``products`` are required. Reactants and products without a ``qty`` value are assumed to appear once
+in the reaction equation. Reactant and product species must be present in the specified phase and include a ``molecular weight [kg mol-1]`` 
+parameter in :math:`\mathrm{kg}\ \mathrm{mole}^{-1}`. The parameter ``aqueous-phase water`` is required and must be the name of the aerosol-phase species that is used for water.
+The parameter ``ion pair`` is optional. When it is included, its value must be the name of an ion pair that is present in the specified aerosol phase.
+Its mean binary activity coefficient will be applied to the reverse reaction.
+
+When ``A`` is not included, it is assumed to be 1.0; when ``C`` is not included, it is assumed to be 0.0. The reverse reaction rate constant ``k_reverse`` is required.
+
+The unit for time is assumed to be s, but inclusion of the optional key-value pair ``time unit = MIN`` can be used to indicate a rate with minutes as the time unit.