Initial draft of automatic docs

.github/workflows/build_docs.yml

@@ -0,0 +1,51 @@
+name: Build Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build-docs:
+    name: build-docs
+    runs-on: ubuntu-latest
+    # Commit step needs write permissions
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v5
+        # The following is needed to allow add-and-commit to know which branch to work on
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+
+      - name: Setup python
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.12.3
+
+      - name: Install dependancies
+        run: python -m pip install -r requirements.txt
+
+      - name: Create config file for MOPPy
+        # Details don't matter
+        run: |
+          [email protected]
+          name=ACCESS-NRI
+          [email protected]
+          mkdir ~/.moppy
+          echo -e "creator_email: $email\ncreator_name: $name\ncreator_url: $url\norganisation: $name" > ~/.moppy/user.yml
+
+      - name: Update specification.md
+        run: python scripts/update_specification.py
+
+      - name: Update mapping.md
+        run: python scripts/update_mapping.py
+
+      - name: Commit updated docs
+        uses: EndBug/add-and-commit@v9
+        with:
+          add: docs/*.md

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: "2"
+
+build:
+  os: "ubuntu-24.04"
+  tools:
+    python: "3"
+
+mkdocs:
+  configuration: mkdocs.yaml
+
+formats:
+  - pdf

README.md

@@ -1,2 +1,13 @@
-# ACCESS_Output_data_specifications
-Provide documentation for users and developers that describes model outputs.
+# ACCESS Output Data Specification
+
+The Access Output Data Specification repository contains the documentation
+describing:
+- The desired output data specification for ACCESS models
+- The mapping from ACCESS model output fields to CMIP7 fields
+
+Much of the content is automatically generated from:
+- The [ACCESS output data schema](https://github.com/ACCESS-NRI/schema/tree/main/au.org.access-nri/model/output/file-metadata)
+- The CMIP7 Data Requests variable metadata (see the [API](https://github.com/CMIP-Data-Request/CMIP7_DReq_Software) and [data](https://airtable.com/apphMYhEwBJfd0bUK/shrYC888Qxf8gkvky))
+- [ACCESS-MOPPy](https://github.com/ACCESS-NRI/ACCESS-MOPPy)'s variable mappings
+
+This information is hosted on readthedocs [here](https://access-output-data-specifications--2.org.readthedocs.build/en/2/).

docs/css/table.css

@@ -0,0 +1,16 @@
+/**
+ * This widens the content to look better on wide screens and
+ * makes the tables wrap contents instead of having the table
+ * horizontally scroll.
+ */
+.wy-nav-content {
+    max-width: 90%;
+}
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal !important;
+}
+
+.wy-table-responsive {
+    overflow : visible !important;
+}

docs/index.md

@@ -0,0 +1,12 @@
+# ACCESS Output Data Specification
+
+These docs describe:
+
+- The desired output data [specification](specification.md) for ACCESS models
+- The [mapping](mapping.md) from ACCESS model output fields to CMIP7 fields
+
+Much of the content is automatically generated from:
+
+- The [ACCESS output data schema](https://github.com/ACCESS-NRI/schema/tree/main/au.org.access-nri/model/output/file-metadata)
+- The CMIP7 Data Requests variable metadata (see the [API](https://github.com/CMIP-Data-Request/CMIP7_DReq_Software) and [data](https://airtable.com/apphMYhEwBJfd0bUK/shrYC888Qxf8gkvky))
+- [ACCESS-MOPPy](https://github.com/ACCESS-NRI/ACCESS-MOPPy)'s variable mappings

docs/javascripts/site.js

@@ -0,0 +1,3 @@
+$(document).ready( function () {
+    $('#mapping').DataTable();
+} );