Big revision of documentation

.github/workflows/docs.yaml

@@ -0,0 +1,47 @@
+name: docs
+
+on:
+  push:
+    branches: [ master ]
+
+jobs:
+  build-and-deploy:
+    name: build and deploy docs
+    runs-on: ubuntu-latest
+    env:
+      MPLBACKEND: 'Agg'
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+
+    - name: Install OQ and dependencies
+      run: |
+        sudo apt-get install -y libspatialindex-dev
+        git clone --depth=1 https://github.com/gem/oq-engine.git
+        cd oq-engine
+        python ./install.py devel
+        cd ..
+        source $HOME/openquake/bin/activate
+        pip install h3
+        pip install -r requirements.txt
+        pip install -e .
+        pip install sphinx furo recommonmark
+
+    - name: Build HTML docs
+      run: |
+        source $HOME/openquake/bin/activate
+        sphinx-build -b html doc_src/source doc_src/build/html
+        touch doc_src/build/html/.nojekyll
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_branch: gh-pages
+        publish_dir: doc_src/build/html/
+        commit_message: "deploy docs from master"

.github/workflows/docs_preview.yaml

@@ -0,0 +1,48 @@
+name: docs preview
+
+on:
+  push:
+    branches: [ docs ]
+
+jobs:
+  build-and-deploy:
+    name: build and deploy docs preview
+    runs-on: ubuntu-latest
+    env:
+      MPLBACKEND: 'Agg'
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+
+    - name: Install OQ and dependencies
+      run: |
+        sudo apt-get install -y libspatialindex-dev
+        git clone --depth=1 https://github.com/gem/oq-engine.git
+        cd oq-engine
+        python ./install.py devel
+        cd ..
+        source $HOME/openquake/bin/activate
+        pip install h3
+        pip install -r requirements.txt
+        pip install -e .
+        pip install sphinx furo recommonmark
+
+    - name: Build HTML docs
+      run: |
+        source $HOME/openquake/bin/activate
+        sphinx-build -b html doc_src/source doc_src/build/html
+        touch doc_src/build/html/.nojekyll
+
+    - name: Deploy preview to gh-pages/preview/docs
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_branch: gh-pages
+        publish_dir: doc_src/build/html/
+        destination_dir: preview/docs
+        commit_message: "docs preview from docs branch"

.github/workflows/test.yaml

@@ -0,0 +1,37 @@
+name: tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  schedule:
+    - cron: "0 1 * * *"
+
+jobs:
+  test:
+    name: pytest
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+    - name: Install OQ and dependencies
+      run: |
+        sudo apt-get install libspatialindex-dev
+        git clone --depth=1 https://github.com/gem/oq-engine.git
+        cd oq-engine
+        python ./install.py devel
+        cd ..
+        source $HOME/openquake/bin/activate
+        pip install h3
+        pip install -r requirements.txt
+        pip install -e .
+        deactivate
+    - name: Run test with pytest
+      run: |
+        source $HOME/openquake/bin/activate
+        pytest openquake tests -W ignore::UserWarning

.gitignore

@@ -70,6 +70,8 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+doc_src/build/
+doc_src/source/_api/
 
 # PyBuilder
 target/

README.md

@@ -1,87 +1,67 @@
 # Hamlet: Hazard Model Evaluation and Testing
 
-Hamlet (`openquake.hme`) is a Python package developed (OK, in
-development) for qualitative and quantitative evaluation of
-Probabilistic Seismic Hazard Analysis (PSHA) models, with the intention
-of providing feedback to modelers during the model construction process,
-to aid model development. Hamlet is developed by the [GEM
+Hamlet (`openquake.hme`) is a Python package for qualitative and quantitative
+evaluation of Probabilistic Seismic Hazard Analysis (PSHA) models, with the
+intention of providing feedback to modelers during the model construction
+process, to aid model development. Hamlet is developed by the [GEM
 Foundation](https://www.globalquakemodel.org), and uses the
 [OpenQuake](https://github.com/GEM/oq-engine) software extensively.
 
-Hamlet will incorporate several model test frameworks, including those
-developed by GEM and some of those developed outside of GEM such as the
-[RELM](http://cseptesting.org/documents/relm.php) tests. Currently, and
-likely in the future, the model files will be required to be in the
-[OpenQuake](https://github.com/GEM/oq-engine) format, regardless of the
-format of their original implementation.
-
-Most of the Hamlet evaluations are spatial in nature; the model domain
-is discretized into grid cells, and comparisons between observations and
-model predictions are performed in each grid cell, to highlight where in
-the domain the model matches the observations, and where it might need
-some refinement.
-
-Additionally, unlike some other hazard model testing frameworks, Hamlet
-is designed to operate on separate components of a hazard model, so that
-each component can be evaluated against its corresponding data. For
-example, each branch of a source model logic tree can be tested
-independently, and each type of source (e.g., subduction megathrust,
-crustal, in-slab) can be tested independently as well, in the spatial
-framework described above.
+Hamlet incorporates several model test frameworks, including those developed by
+GEM and some of those developed outside of GEM such as the
+[RELM/CSEP](http://cseptesting.org/documents/relm.php) tests. The model files
+must be in the [OpenQuake](https://github.com/GEM/oq-engine) format.
+
+Most of the Hamlet evaluations are spatial in nature; the model domain is
+discretized into grid cells, and comparisons between observations and model
+predictions are performed in each grid cell, to highlight where in the domain
+the model matches the observations, and where it might need some refinement.
+
+Additionally, unlike some other hazard model testing frameworks, Hamlet is
+designed to operate on separate components of a hazard model, so that each
+component can be evaluated against its corresponding data. For example, each
+branch of a source model logic tree can be tested independently, and each type
+of source (e.g., subduction megathrust, crustal, in-slab) can be tested
+independently as well, in the spatial framework described above.
 
 ## Quickstart
 
 ### Installation
 
-Hamlet requires installation Python v.3.7+, the
-[OpenQuake](https://github.com/GEM/oq-engine) engine, and some
-additional dependencies as well. These are specified in the
-`requirements.txt` file.
-
-(*Note:* A few of the dependencies might be challenging to install.
-These are [Rtree](https://toblerity.org/rtree/) and
-[h3-py](https://github.com/uber/h3-py). You may have to install
-`libspatialindex` or `libspatialindex-dev` on Linux or MacOS first,
-depending on your system, for `Rtree`. `h3-py` requires `cc` and `make`,
-but then on Linux/MacOS can be installed easily. Please see the
-documentation for each.)
-
-First, install the [OpenQuake](https://github.com/GEM/oq-engine) engine,
-following directions on that website. You probably want to install it
-into a virtual environment, and you may even want to have a separate
-virtual environment for running Hamlet than the
-[OpenQuake](https://github.com/GEM/oq-engine) virtual environment that
-you normally use (this is up to you).
+Hamlet requires Python 3.11+ and the
+[OpenQuake](https://github.com/GEM/oq-engine) engine.
+
+First, install the OpenQuake engine, following directions on that website. You
+probably want to install it into a virtual environment.
 
 Then, clone the Hamlet repository, and from that directory, install the
 requirements:
 
 ```bash
-    pip install -r requirements.txt
+pip install -r requirements.txt
 ```
 
 and then install Hamlet:
 
 ```bash
-    pip install -e .
+pip install -e .
 ```
 
 ### Running Hamlet
 
-Hamlet only requires a seismic hazard model (implemented in
-[OpenQuake](https://github.com/GEM/oq-engine)) and a processed seismic
-catalog (declustered, and ideally classified by source type) to run.
-Once installed, Hamlet can be run from the command line:
+Hamlet requires a seismic hazard model (implemented in OpenQuake) and a
+processed seismic catalog (declustered, and ideally classified by source type)
+to run. Once installed, Hamlet can be run from the command line:
 
 ```bash
-    hamlet test_model.yml
+hamlet test_model.yml
 ```
 
-`test_model.yml` is a configuration file in
-[YAML](https://yaml.org) format that specifies the source model, seismic
-catalog, tests to be run, and other variables and parameters.
+`test_model.yml` is a configuration file in [YAML](https://yaml.org) format
+that specifies the source model, seismic catalog, tests to be run, and other
+variables and parameters.
 
 ## Documentation
 
-Hamlet documentation can currently be found at 
-https://cossatot.gitlab.io/hamlet/ .
+Hamlet documentation can be found at
+https://gemsciencetools.github.io/hamlet/ .

doc_src/source/_static/custom.css

@@ -0,0 +1,10 @@
+/* Expand top two levels of sidebar nav by default */
+.sidebar-tree .toctree-l1 > ul,
+.sidebar-tree .toctree-l2 > ul {
+    display: block !important;
+}
+
+.sidebar-tree .toctree-l1 > label,
+.sidebar-tree .toctree-l2 > label {
+    display: none;
+}

doc_src/source/api.rst

@@ -0,0 +1,12 @@
+=============
+API Reference
+=============
+
+.. autosummary::
+   :toctree: _api
+   :recursive:
+
+   openquake.hme.core
+   openquake.hme.model_test_frameworks
+   openquake.hme.utils
+   openquake.hme.reporting