Address the RAVEN 3 Guide review

.github/workflows/examples.yml

@@ -17,13 +17,15 @@ on:
       - "scripts/run_examples.py"
       - ".github/workflows/examples.yml"
       - "raven-toolbox"
+      - "RAVEN"
   pull_request:
     paths:
       - "docs/guide/**"
       - "docs/data/**"
       - "scripts/run_examples.py"
       - ".github/workflows/examples.yml"
       - "raven-toolbox"
+      - "RAVEN"
   schedule:
     - cron: "0 5 * * 1"
   workflow_dispatch:
@@ -51,32 +53,12 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           # GLPK arrives as a wheel via cobrapy's optlang/swiglpk dependency, so
-          # no system solver has to be installed. openpyxl is needed by the
-          # Excel export example, gurobipy by the ones marked needs-gurobi.
+          # no system solver has to be installed; it solves the LPs and MILPs.
+          # openpyxl is needed by the Excel export example, gurobipy by the
+          # quadratic MOMA example, which needs a QP solver. The size-limited
+          # licence that comes with the gurobipy wheel covers a model that small.
           python -m pip install "./raven-toolbox[excel]" gurobipy
 
-      # A Gurobi Web License Service licence, if the repository has one, lets the
-      # examples marked `needs-gurobi` run -- the MILP ones GLPK cannot solve.
-      # Without the secrets the step is a no-op and those examples stay skipped.
-      - name: Configure the Gurobi licence
-        env:
-          WLSACCESSID: ${{ secrets.GUROBI_WLSACCESSID }}
-          WLSSECRET: ${{ secrets.GUROBI_WLSSECRET }}
-          LICENSEID: ${{ secrets.GUROBI_LICENSEID }}
-        run: |
-          if [ -z "$WLSACCESSID" ]; then
-            echo "No Gurobi licence configured -- needs-gurobi examples will be skipped."
-            exit 0
-          fi
-          umask 077
-          {
-            echo "WLSACCESSID=$WLSACCESSID"
-            echo "WLSSECRET=$WLSSECRET"
-            echo "LICENSEID=$LICENSEID"
-          } > "$RUNNER_TEMP/gurobi.lic"
-          echo "GRB_LICENSE_FILE=$RUNNER_TEMP/gurobi.lic" >> "$GITHUB_ENV"
-          echo "RAVEN_DOCS_GUROBI=1" >> "$GITHUB_ENV"
-
       - name: Report versions
         run: |
           python -c "import cobra, raven_toolbox, optlang; print('cobra', cobra.__version__); print('raven_toolbox', raven_toolbox.__version__); print('solvers', sorted(optlang.available_solvers))"
@@ -110,8 +92,9 @@ jobs:
         with:
           python-version: "3.12"
 
-      # Gurobi's MATLAB interface, for the examples marked `needs-gurobi`. Both
-      # steps are no-ops when the repository has no licence secrets.
+      # Gurobi's MATLAB interface, for the examples marked `needs-gurobi`: MILPs
+      # that RAVEN also solves on its bundled GLPK, but that the page runs on
+      # Gurobi. Both steps are no-ops when the repository has no licence secrets.
       - name: Install Gurobi for MATLAB
         env:
           WLSACCESSID: ${{ secrets.GUROBI_WLSACCESSID }}

.github/workflows/update-submodules.yml

@@ -28,7 +28,7 @@ jobs:
           # it out at its tip. Done explicitly because the submodules are
           # `shallow = true`, so only the pinned commit is present and
           # `git submodule update --remote` can't resolve the remote branch ref.
-          # (RAVEN -> develop3, raven-toolbox -> develop, hanpo-GEM -> main)
+          # (RAVEN -> develop, raven-toolbox -> develop, hanpo-GEM -> main)
           git submodule sync --recursive
           git submodule foreach '
             branch=$(git config -f "$toplevel/.gitmodules" "submodule.$name.branch" || echo main)

.gitignore

@@ -164,13 +164,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
-/site
-
-# Sphinx exploration (explore/pydata-sphinx-theme): generated at build time
-# by scripts/gen_api_pages_sphinx.py, the same way the MkDocs build's API
-# pages exist only in mkdocs-gen-files' virtual filesystem, never in git.
-.venv-sphinx/
+# API reference pages, generated at build time by scripts/gen_api_pages.py
 docs/api/matlab/*.md
 docs/api/python/*.md
 docs/matlab-vs-python.md

.readthedocs.yaml

@@ -20,4 +20,4 @@ sphinx:
 
 python:
   install:
-    - requirements: requirements-sphinx.txt
+    - requirements: requirements.txt

DESIGN.md

@@ -25,19 +25,19 @@
 A single, dual-language documentation site for **RAVEN** that serves both the
 **MATLAB** toolbox and the **Python** package (**raven-toolbox**) from one place,
 so a user can learn a concept once and apply it in either language. The site is
-built with [MkDocs](https://www.mkdocs.org/) +
-[Material](https://squidfunk.github.io/mkdocs-material/) and published on Read
-the Docs.
+built with [Sphinx](https://www.sphinx-doc.org/), [MyST](https://myst-parser.readthedocs.io/)
+Markdown and the [PyData theme](https://pydata-sphinx-theme.readthedocs.io/), and
+published on Read the Docs.
 
 ## 2. Guiding principles
 
 - **Dual-language parity.** MATLAB and Python are presented side by side
   throughout: paired API entries, and code blocks with MATLAB/Python tabs.
 - **Single source of truth.** API documentation is extracted directly from the
-  function help in each toolbox's source (via `mkdocstrings`), so it never
+  function help in each toolbox's source, so it never
   drifts from the code. The source repos are tracked as **git submodules**.
 - **Source of truth follows the active branch.** The RAVEN submodule tracks
-  **`develop3`** and raven-toolbox tracks **`develop`**. develop3's modular
+  **`develop`** and raven-toolbox tracks **`develop`**. RAVEN's modular
   folder layout (`reconstruction`, `manipulation`, `analysis`, …) mirrors
   raven-toolbox's package structure, so the two line up by category.
 - **Don't reinvent cobrapy.** Where the Python version intentionally relies on
@@ -50,18 +50,16 @@ the Docs.
 
 ## 3. Technical foundation
 
-- MkDocs + Material theme; Read the Docs build (`.readthedocs.yaml`).
-- `mkdocstrings` with two handlers, both collecting statically from submodule
-  source (no MATLAB runtime, no installed package required):
-  - Python handler (griffe) over the raven-toolbox source, NumPy docstring style.
-  - MATLAB handler (`mkdocstrings-matlab`, tree-sitter) over the RAVEN modular
-    directories, NumPy docstring style.
+- Sphinx + MyST Markdown + PyData theme, with `sphinx-design` for tabs, grids
+  and badges; Read the Docs build (`.readthedocs.yaml`, `docs/conf.py`,
+  `requirements.txt`).
 - Function help in both toolboxes uses **NumPy-style docstrings** so it renders
   as structured argument/return tables.
-- The API reference is **generated at build time** (`mkdocs-gen-files` +
-  `mkdocs-literate-nav`): a cobrapy-style autoapi, one page per category, with
-  MATLAB and Python paired by name.
-- Submodules: `RAVEN` (branch `develop3`), **raven-toolbox** (branch
+- The API reference is **generated at build time** by `scripts/gen_api_pages.py`,
+  called from `docs/conf.py`. It reads the help statically from submodule source
+  (no MATLAB runtime, no installed package) and writes a cobrapy-style autoapi,
+  one page per category, with MATLAB and Python paired by name.
+- Submodules: `RAVEN` (branch `develop`), **raven-toolbox** (branch
   `develop`), `hanpo-GEM` (branch `main`).
 
 ## 4. Site structure
@@ -83,10 +81,9 @@ the Docs.
 An **Installation** section with an overview page and a **separate page per
 version**:
 
-- **RAVEN (MATLAB).** Requirements, then the **three install methods** from the
-  [wiki](https://github.com/SysBioChalmers/RAVEN/wiki/Installation), the
+- **RAVEN (MATLAB).** Requirements, then the **three install methods**: the
   MATLAB Add-Ons manager, a release download, and `git clone`, plus
-  verifying (`checkInstallation`), **upgrading** (per method) and **removing**
+  verifying (`checkRaven`), **upgrading** (per method) and **removing**
   (`removeRavenFromPath`).
 - **Python (raven-toolbox).** Requirements, `pip install raven-toolbox`,
   development install, verifying, **upgrading** and **removing**, and solver
@@ -121,7 +118,7 @@ Then a **mapping table**: MATLAB function name (left) ↔ Python function name
 |---|---|
 | `importModel` | `import_model` |
 | `solveLP` | `solve_lp` |
-| … | … (cobrapy) :material-link-variant: |
+| … | … (cobrapy) |
 
 ### 4.4 Guides
 
@@ -149,15 +146,16 @@ Conventions:
 
 - **Page anatomy.** Title and one-paragraph statement of the task; a
   "Functions on this page" table (MATLAB | Python | note) linking into the API
-  reference; setup; two to five numbered steps, each with a tabbed code block and
+  reference (`scripts/autolink.py` adds the links at build time: every name in
+  the table and the first mention per section in the prose); setup; two to five numbered steps, each with a tabbed code block and
   its real output; "What can go wrong"; "See also".
 - **cobrapy is marked, three ways**: a badge in the function table linking to
   cobrapy's docs, an explicit import in the snippet
   (`from cobra.io import read_sbml_model`), and a line of prose wherever the
   MATLAB tab would make a cobrapy call look like RAVEN's. A reader who thinks
   `get_by_id` is raven-toolbox's searches the wrong reference.
 - **Never fake a pairing.** Where nothing equivalent exists, the tab says so.
-  `scripts/check_names.py` fails the build on an invented name.
+  `scripts/check_names.py` lists names that resolve to neither toolbox.
 - **Differences are the content.** Where the two toolboxes genuinely disagree,
   `getExchangeRxns` counting 273 exchanges where `model.exchanges` counts 270,
   `fillGaps` being a MILP where `connect_blocked_reactions` is an LP, say so on
@@ -221,13 +219,13 @@ Generated from source, organised so each function is shown for both languages.
   <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html> and a
   function page like
   <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/flux_analysis/parsimonious/index.html#cobra.flux_analysis.parsimonious.pfba>.
-- **MATLAB**: functions organised **by subfolder** (the `develop3` modular
+- **MATLAB**: functions organised **by subfolder** (RAVEN's modular
   categories: `reconstruction`, `manipulation`, `analysis`, …).
 
 ## 5. Conventions
 
-- **Code tabs.** Material content tabs labelled "MATLAB" / "Python", **linked
-  and persistent**, defaulting to **MATLAB**.
+- **Code tabs.** `sphinx-design` tabs labelled "MATLAB" / "Python", **linked**
+  through `:sync:`, defaulting to **MATLAB**.
 - **cobrapy indicator.** Functions that resolve to cobrapy (not RAVEN) are
   marked with a consistent icon/badge and link out to the cobrapy docs.
 - **Naming.** MATLAB `camelCase` ↔ Python `snake_case`; the two are paired by
@@ -246,8 +244,9 @@ into the relevant section above.)*
 
 *(Append decisions here as they are made.)*
 
-- Build stack: MkDocs + Material + `mkdocstrings` (Python + MATLAB handlers).
-- Source via git submodules: RAVEN tracks `develop3`, **raven-toolbox tracks
+- Build stack: Sphinx + MyST + PyData theme; API pages generated by
+  `scripts/gen_api_pages.py`.
+- Source via git submodules: RAVEN tracks `develop`, **raven-toolbox tracks
   `develop`**, hanpo-GEM tracks `main`.
 - The Python package is named **raven-toolbox**.
 - Function help reformatted to NumPy-style docstrings (renders as tables).

README.md

@@ -2,15 +2,17 @@
 
 Documentation site for **RAVEN** (the MATLAB toolbox) and **raven-toolbox** (the
 Python port) for genome-scale metabolic model reconstruction, analysis and
-visualization. Built with [MkDocs](https://www.mkdocs.org/) +
-[Material](https://squidfunk.github.io/mkdocs-material/) and published on Read
-the Docs.
+visualization. Built with [Sphinx](https://www.sphinx-doc.org/),
+[MyST](https://myst-parser.readthedocs.io/) Markdown and the
+[PyData theme](https://pydata-sphinx-theme.readthedocs.io/), and published on
+Read the Docs.
 
 The site combines:
 
-- a side-by-side **API reference** auto-generated from the function comments of
-  both toolboxes (via [mkdocstrings](https://mkdocstrings.github.io/) with its
-  Python and MATLAB handlers);
+- a side-by-side **API reference** generated from the function comments of
+  both toolboxes;
+- a **guide** of task pages with MATLAB and Python side by side, whose examples
+  are executed and checked against their printed output;
 - the **RAVEN tutorials**; and
 - a complete, worked **GEM reconstruction protocol** (the *Hansenula
   polymorpha* `hanpo-GEM` example).
@@ -24,19 +26,29 @@ set in `.gitmodules`: [`RAVEN`](https://github.com/CompMetEng/RAVEN) and
 
 ```bash
 # clone with submodules
-git clone --recurse-submodules https://github.com/edkerk/raven-docs.git
+git clone --recurse-submodules https://github.com/CompMetEng/raven-docs.git
 cd raven-docs
 # (if already cloned: git submodule update --init --recursive)
 
 python -m venv .venv
-source .venv/Scripts/activate      # Windows; use .venv/bin/activate on macOS/Linux
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
 pip install -r requirements.txt
 
-mkdocs serve     # live preview at http://127.0.0.1:8000
-mkdocs build     # static site into ./site
+sphinx-build -b html docs docs/_build/html
 ```
 
-The API reference pages are generated at build time by
-[`scripts/gen_api_pages.py`](scripts/gen_api_pages.py), which walks the two
-toolbox submodules and pairs their functions. No MATLAB runtime or installed
-Python package is required; docstrings are collected statically from source.
+The API reference pages are generated at the start of each build by
+[`scripts/gen_api_pages.py`](scripts/gen_api_pages.py), called
+from `docs/conf.py`, which walks the two toolbox submodules and pairs their
+functions. No MATLAB runtime or installed Python package is required;
+docstrings are collected statically from source.
+[`scripts/autolink.py`](scripts/autolink.py) then links the function names on
+the guide pages to those reference pages, and cobrapy names to cobrapy's
+documentation through its intersphinx inventory.
+
+## Checking the guide examples
+
+[`scripts/run_examples.py`](scripts/run_examples.py) runs the code blocks on the
+guide pages, MATLAB and Python, and compares what each prints with the `text`
+block below it; `--update` rewrites those blocks. The
+[Guide examples](.github/workflows/examples.yml) workflow runs it in CI.