Merge branch 'mkdocs'

* mkdocs: (22 commits) Convert examples/doctest Dont complain about relative (working) links Update notebooks for doc rendering Plotting compatibility Some md linting Dont autoformat examples Fix image paths Update dev_guide for new mkdocs Update ref to examples/ Deploy docs Convert citations Simplify bibliography Move images Include image/snippets Enable mkdocs-jupyter Fix mkdocstring warnings Update Parameters syntax Convert more cross-references Convert cross-references Convert admonitions/callouts ...
nansencenter · Oct 31, 2024 · d3223b4 · d3223b4
2 parents 05e6aa1 + 13fcaaa
commit d3223b4
Show file tree

Hide file tree

Showing 125 changed files with 9,388 additions and 1,667 deletions.
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -1,8 +1,5 @@
-# From https://github.com/mitmproxy/pdoc/blob/main/.github/workflows/docs.yml
-# with minor adaptations
-
-name: Deploy docs
-
+# From https://github.com/mhausenblas/mkdocs-deploy-gh-pages
+name: Publish mkDocs via GitHub Pages
 # build the documentation whenever there are new commits on main
 on:
   push:
@@ -12,38 +9,18 @@ on:
     # tags:
     #   - '*'
 
-# security: restrict permissions for CI jobs.
-permissions:
-  contents: read
-
 jobs:
-  # Build the documentation and upload the static HTML files as an artifact.
   build:
+    name: Deploy MkDocs
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: '3.10'
-
-      - run: pip install -e .[build]
-      - run: pdoc -o docs-generated/ -t docs/templates --math --docformat=numpy docs/bib/bib.py docs/dev_guide.py ./dapper
+      - name: Checkout main
+        uses: actions/checkout@v2
 
-      - uses: actions/upload-pages-artifact@v1
-        with:
-          path: docs-generated/
-
-  # Deploy the artifact to GitHub pages.
-  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
-  deploy:
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v1
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: mkdocs.yml
+          REQUIREMENTS: requirements.txt
+          # CUSTOM_DOMAIN: optionaldomain.com
diff --git a/.gitignore b/.gitignore
@@ -154,9 +154,6 @@ cython_debug/
 # Don't commit results
 dpr_data/
 
-# Don't include local builds of docs
-doc-build
-
 # Generated when running QG model
 dapper/mods/QG/f90/prms_*\.txt
 

diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -0,0 +1,9 @@
+# markdownlint (js library) config
+MD052: false
+first-line-h1: false
+no-multiple-blanks: false
+line-length: false
+# MD029:
+#   style: "ordered"
+# MD007: false
+# "MD007": { "indent": 4 }
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 !
 -->
 
-<img src="/docs/imgs/logo_wtxt.png" align="left" width="250"/>
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/logo_wtxt.png" align="left" width="250"/>
 
 DAPPER is a set of templates for **benchmarking** the performance of **data assimilation** (DA) methods.
 The numerical experiments provide support and guidance for new developments in DA.
@@ -27,7 +27,7 @@ and then estimate that truth given the models and noisy observations.
 ## Getting started
 
 [Install](#installation), then
-read, run and try to understand `examples/basic_{1,2,3}.py`.
+read, run and try to understand `docs/examples/basic_{1,2,3}.py`.
 Some of the examples also exist as Jupyter notebooks, and can be run in the cloud
 *without installation* (but requiring Google login): [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](http://colab.research.google.com/github/nansencenter/DAPPER).
 This [screencast](https://www.youtube.com/watch?v=YtalK0Zkzvg&t=6475s)
@@ -49,7 +49,7 @@ through a variety of typical [test cases](#test-cases-models) and statistics. It
 (b) facilitates comparative studies, thus promoting the
 (a) reliability and
 (b) relevance of the results.
-For example, the figure below is generated by `examples/basic_3.py`,
+For example, the figure below is generated by `docs/examples/basic_3.py`,
 reproduces figure 5.7 of [these lecture notes](http://cerea.enpc.fr/HomePages/bocquet/teaching/assim-mb-en.pdf).
 DAPPER is
 (c) open source, written in Python, and
@@ -59,10 +59,10 @@ this promotes the
 (d) dissemination of the underlying science,
 and makes it easy to adapt and extend.
 
-![Comparative benchmarks with Lorenz-96 plotted as a function of the ensemble size (N)](./docs/imgs/ex3.svg)
+![Comparative benchmarks with Lorenz-96 plotted as a function of the ensemble size (N)](https://github.com/nansencenter/DAPPER/raw/master/docs/images/ex3.svg)
 
 DAPPER demonstrates how to parallelise ensemble forecasts (e.g., the QG model),
-local analyses (e.g., the LETKF), and independent experiments (e.g., `examples/basic_3.py`).
+local analyses (e.g., the LETKF), and independent experiments (e.g., `docs/examples/basic_3.py`).
 It includes a battery of diagnostics and statistics,
 which all get averaged over subdomains (e.g., "ocean" and "land") and then in time.
 Confidence intervals are computed, including correction for auto-correlations,
@@ -72,7 +72,7 @@ which may be paused for further interactive inspection.
 In summary, DAPPER is well suited for teaching and fundamental DA research.
 Also see its [drawbacks](#similar-projects).
 
-![EnKF - Lorenz-96](./docs/imgs/ex1.jpg)
+![EnKF - Lorenz-96](https://github.com/nansencenter/DAPPER/raw/master/docs/images/ex1.jpg)
 
 <!-- Non-highlighted features:
 - Time sequences use via `tools.chronos.Chronology` and `tools.chronos.Ticker`.
@@ -132,7 +132,7 @@ You should now be able to do run your script with
 `python path/to/script.py`.  
 For example, if you are in the DAPPER dir,
 
-    python examples/basic_1.py
+    python docs/examples/basic_1.py
 
 **PS**: If you closed the terminal (or shut down your computer),
 you'll first need to run `conda activate dapper-env`
@@ -352,11 +352,11 @@ and the Center for Western Weather and Water Extremes (CW3E).
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable line-length -->
-![NORCE](./docs/imgs/norce-logo.png)
-![NERSC](./docs/imgs/nansen-logo.png)
-<img src="https://github.com/nansencenter/DAPPER/blob/master/docs/imgs/UoR-logo.png?raw=true" height="120" />
-<img src="https://github.com/nansencenter/DAPPER/blob/master/docs/imgs/nceologo1000.png?raw=true" height="100">
-<img src="./docs/imgs/CW3E-Logo-Horizontal-FullColor.png?raw=true" width="400">
+![NORCE](https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/norce-logo.png)
+![NERSC](https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/nansen-logo.png)
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/UoR-logo.png?raw=true" height="120" />
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/nceologo1000.png?raw=true" height="100">
+<img src="https://github.com/nansencenter/DAPPER/raw/master/docs/images/logos/CW3E-Logo-Horizontal-FullColor.png?raw=true" width="400">
 <!-- markdownlint-restore -->
 
 ## Publications

diff --git a/dapper/README.md b/dapper/README.md
@@ -1,43 +1,17 @@
-## API reference
-
-Click the links in the navigation menu to view
-the docs for the various modules.
-
-## Installation
-
-See [README/Installation](https://github.com/nansencenter/DAPPER#installation)
-
-## Usage
-
-See [README/Getting-started](https://github.com/nansencenter/DAPPER#getting-started)
-
-##### Examples
-
-See [examples/README](https://github.com/nansencenter/DAPPER/tree/master/examples)
-
 ##### Adding your own model/method
 
 If you wish to illustrate and run benchmarks with
 your own **model** or **method**, then
 
 - If it is a complex one, you may be better off using DAPPER
   merely as *inspiration* (but you can still
-  [cite it](https://github.com/nansencenter/DAPPER#getting-started))
+  [cite it](../#getting-started))
   rather than trying to squeeze everything into its templates.
 - If it is relatively simple, however, you may well want to use DAPPER.
   In that case, read this:
-    - `dapper.mods`
-    - `dapper.da_methods`
+    - [`mods`](mods)
+    - [`da_methods`](da_methods)
 
 Since the generality of DAPPER is
-[limited](https://github.com/nansencenter/DAPPER#similar-projects)
+[limited](../#similar-projects)
 it is quite likely you will also need to make changes to the DAPPER code itself.
-
-## Developer guide
-
-If you are making a pull request, please read the [developer guide](dev_guide).
-
-## Bibliography
-
-Click the various citations/references (e.g. `bib.anderson2010non`)
-to access the [bibliography](bib).
diff --git a/dapper/__init__.py b/dapper/__init__.py
@@ -1,7 +1,7 @@
 """Root package of **DAPPER**
 (Data Assimilation with Python: a Package for Experimental Research)
 
-.. include:: ./README.md
+--8<-- "dapper/README.md"
 """
 
 __version__ = "1.7.0"

diff --git a/dapper/da_methods/README.md b/dapper/da_methods/README.md
@@ -1,14 +1,12 @@
-Also see the section on
-[DA Methods](https://github.com/nansencenter/DAPPER#DA-Methods)
-in the main README
+Also see [this section on DA Methods](../../#da-methods)
 for an overview of the methods included with DAPPER.
 
 ## Defining your own method
 
 Follow the example of one of the methods within one of the
 sub-directories/packages.
 The simplest example is perhaps
-`dapper.da_methods.ensemble.EnKF`.
+[`da_methods.ensemble.EnKF`][].
 
 ## General advice for programming/debugging scientific experiments
 

diff --git a/dapper/da_methods/__init__.py b/dapper/da_methods/__init__.py
@@ -1,6 +1,6 @@
 """Contains the data assimilation methods included with DAPPER.
 
-.. include:: ./README.md
+--8<-- "dapper/da_methods/README.md"
 """
 
 from pathlib import Path
@@ -16,7 +16,7 @@ def da_method(*default_dataclasses):
     The decorated classes are defined like a `dataclass`,
     but are decorated by `@da_method()` instead of `@dataclass`.
 
-    .. note::
+    !!! note
         The classes must define a method called `assimilate`.
         This method gets slightly enhanced by this wrapper which provides:
 
@@ -25,7 +25,8 @@ def da_method(*default_dataclasses):
         - Duration timing
         - Progressbar naming magic.
 
-    Example:
+    Examples
+    --------
     >>> @da_method()
     ... class Sleeper():
     ...     "Do nothing."
@@ -43,7 +44,6 @@ def da_method(*default_dataclasses):
     which enables defining default parameters which can be inherited,
     similar to subclassing.
 
-    Example:
     >>> class ens_defaults:
     ...     infl : float = 1.0
     ...     rot  : bool  = False
@@ -56,13 +56,13 @@ def da_method(*default_dataclasses):
     ...     def assimilate(self, HMM, xx, yy):
     ...         ...
 
-    .. note::
+    !!! note
         Apart from what's listed in the above `Note`, there is nothing special to the
         resulting `xp`.  That is, just like any Python object, it can serve as a data
         container, and you can write any number of attributes to it (at creation-time,
         or later).  For example, you can set attributes that are not used by the
         `assimilate` method, but are instead used to customize other aspects of the
-        experiments (see `dapper.xp_launch.run_experiment`).
+        experiments (see [`xp_launch.run_experiment`][]).
     """
     import dataclasses
     import functools

diff --git a/dapper/da_methods/baseline.py b/dapper/da_methods/baseline.py
@@ -1,6 +1,6 @@
 """Unsophisticated" but robust (widely applicable) DA methods.
 
-Many are based on `bib.raanes2016thesis`.
+Many are based on [raanes2016thesis][].
 """
 
 from typing import Callable, Optional
@@ -146,10 +146,15 @@ def fit_sigmoid(Sb, L, kb):
 
     The "normalized" sigmoid, `S1`, is symmetric around 0, and `S1(-∞)=0` and `S1(∞)=1`.
 
-    The sigmoid `S(k) = S1(a*(k-kb) + b)` is fitted (see docs/snippets/sigmoid.jpg) with
+    The sigmoid `S(k) = S1(a*(k-kb) + b)` is fitted with
 
     - `a` corresponding to a given corr. length `L`.
     - `b` to match values of `S(kb)` and `Sb`
+
+    <figure markdown="span">
+        ![](../../images/snippets/sigmoid.jpg){ width="300" }
+        <figcaption>Illustration</figcaption>
+    </figure>
     """
 
     def sigmoid(k):