Documentation improvements

.github/problem-matchers/sphinx.json

@@ -0,0 +1,40 @@
+{
+    "problemMatcher": [
+        {
+            "owner": "sphinx-problem-matcher",
+            "pattern": [
+                {
+                    "regexp": "^(.*):(\\d+):\\s+(\\w*):\\s+(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "severity": 3,
+                    "message": 4
+                }
+            ]
+        },
+        {
+            "owner": "sphinx-problem-matcher-loose",
+            "pattern": [
+                {
+                    "_comment": "A bit of a looser pattern, doesn't look for line numbers, just looks for file names relying on them to start with / and end with .rst",
+                    "regexp": "(\/.*\\.rst):\\s+(\\w*):\\s+(.*)$",
+                    "file": 1,
+                    "severity": 2,
+                    "message": 3
+                }
+            ]
+        },
+        {
+            "owner": "sphinx-problem-matcher-loose-no-severity",
+            "pattern": [
+                {
+                    "_comment": "Looks for file names ending with .rst and line numbers but without severity",
+                    "regexp": "^(.*\\.rst):(\\d+):(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "message": 3
+                }
+            ]           
+        }
+    ]
+}

.github/workflows/doc-build.yml

@@ -0,0 +1,44 @@
+name: Documentation
+env:
+  PYTHON_VERSION: "3.12"
+  POETRY_VERSION: "1.4"
+on: push
+jobs:
+  sphinx:
+    # Note that we only do this on one platform and with the earliest reasonable Python
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Init Python ${{ env.PYTHON_VERSION }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+      - name: Init Poetry ${{ env.POETRY_VERSION }}
+        run: |
+          python -m pip install poetry==${{ env.POETRY_VERSION }}
+          poetry config virtualenvs.in-project true
+          poetry config installer.modern-installation false
+      - name: Cache Virtual Environment
+        uses: actions/cache@v4
+        with:
+          path: ./.venv
+          key: ${{ runner.os }}-sphinx-${{ env.PYTHON_VERSION }}-venv-${{ hashFiles('**/poetry.lock') }}
+      - name: Install Dependencies
+        run: |
+          poetry install
+      - name: Configure Problem Matcher
+        run: echo "::add-matcher::.github/problem-matchers/sphinx.json"
+        # See: https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md
+        # See: https://github.com/python/cpython/pull/20325
+      - name: Run Sphinx
+        run: |
+          poetry run make clean html
+        working-directory: docs
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: hpcflow-documentation (${{ github.sha }})
+          path: docs/build/html
+          if-no-files-found: error
+  # TODO: Publish the docs to an internal site

docs/source/conf.py

@@ -234,6 +234,7 @@ def prepare_task_schema_action_info(app):
     "sphinx.ext.autosummary",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosectionlabel",
+    "sphinx.ext.todo",
     "sphinx_jinja",
     "sphinx_copybutton",
     "sphinx_click",

docs/source/contribute/index.rst

@@ -15,8 +15,7 @@ Recommended reads
 Installation for development
 ============================
 
-`Install poetry <https://python-poetry.org/docs/#installation>`_
-----------------------------------------------------------------
+`Install poetry <https://python-poetry.org/docs/#installation>`_ first.
 
 
 Clone repo
@@ -27,14 +26,14 @@ Clone the git repo (see ssh links below), and then make sure that you switch to
 
 This branch is protected, so create a feature branch before pushing to the repo.
 
-hpcflow
-.........
+Checking out hpcflow
+....................
 ::
 
    git clone git@github.com:hpcflow/hpcflow-new.git
 
-matflow
-........
+Checking out matflow
+....................
 ::
 
    git clone git@github.com:hpcflow/matflow-new.git
@@ -78,17 +77,17 @@ Open the virtual enviroment with::
 
    poetry shell
 
-hpcflow
---------
-CLI
-....
+Working with hpcflow
+--------------------
+
 You can interact with the CLI by calling::
 
    python3 hpcflow/cli/cli.py --help
 
 
-matflow
---------
+Working with matflow
+--------------------
+
 link to local hpcflow
 ......................
 To be able to work with hpcflow and immediately see the changes reflected in matflow you need to reconfigure the hpcflow dependency to point to your local copy of hpcflow.

docs/source/user/how_to/index.rst

@@ -8,6 +8,7 @@ This help snippets guide you through common quick tasks in |app_name|.
 
    Configuration <config>
    Task Schemas <task_schemas>
+   Template Components <template_components>
    Workflow Templates <workflow_templates>
    Workflows <workflows>
    Environments <environments>

docs/source/user/how_to/workflows.rst

@@ -37,4 +37,4 @@ We support paths like:
 * `ssh://user@host/path/to/workflow.json` for remote json
 * `https://sandbox.zenodo.org/record/1210144/files/workflow.zip` for zenodo zarr-zip
 
-You can convert a zarr store to a zarr-zip store using `Workflow.to_zip()`.
+You can convert a zarr store to an archived zarr-zip store using `Workflow.zip()`.

hpcflow/data/demo_data/__init__.py

@@ -1 +1,8 @@
-# required for `demo_data` to be accessible as a package resource in Python 3.8/3.9
+"""
+Data for the demonstration workflows.
+
+Note
+----
+This is required for `demo_data` to be accessible as a package resource in
+Python 3.8/3.9.
+"""

hpcflow/data/demo_data_manifest/__init__.py

@@ -0,0 +1,3 @@
+"""
+Manifest for demonstration data.
+"""

hpcflow/sdk/__init__.py

@@ -4,7 +4,8 @@
 import os
 import sys
 
-# classes used in the construction of a workflow:
+#: Classes used in the construction of a workflow.
+#: :meta hide-value:
 sdk_classes = {
     "Workflow": "hpcflow.sdk.core.workflow",
     "Task": "hpcflow.sdk.core.task",
@@ -95,6 +96,8 @@
 }
 
 # these are defined as `BaseApp` methods with an underscore prefix:
+#: Functions exported by the application.
+#: :meta hide-value:
 sdk_funcs = (
     "make_workflow",
     "make_demo_workflow",