Resolve the function mapping, split two long pages, and fix 3.0.0b1 install instructions

docs/conf.py

@@ -57,7 +57,20 @@
     # clicked, rather than the whole tree opening at once.
     "collapse_navigation": True,
     "show_toc_level": 2,
-    "github_url": "https://github.com/SysBioChalmers/RAVEN",
+    "icon_links": [
+        {
+            "name": "RAVEN (MATLAB) on GitHub",
+            "url": "https://github.com/SysBioChalmers/RAVEN",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+        {
+            "name": "raven-toolbox (Python) on GitHub",
+            "url": "https://github.com/SysBioChalmers/raven-toolbox",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        },
+    ],
     "use_edit_page_button": False,
     "navbar_end": ["theme-switcher", "navbar-icon-links"],
     # The wordmark already carries the "RAVEN" text, so no separate navbar

docs/guide/index.md

@@ -126,9 +126,10 @@ not yet at parity between the two toolboxes.
 
 ```{toctree}
 :hidden:
-:caption: Installation
+:caption: Start
 
 ../installation/index
+../yaml-format
 ```
 
 ```{toctree}

docs/guide/io.md

@@ -56,7 +56,7 @@ makes those annotations unusable as a key for matching metabolites across
 models.
 
 `importModel` accepts SBML Level 3 Version 1 with FBC version 2 and errors
-on anything older; see the [RAVEN 3 migration guide](../raven3-migration.md#sbml-io)
+on anything older; see the [RAVEN 3 migration guide](../raven3-migration/formats-and-reconstruction.md#sbml-io)
 if a file is rejected.
 :::
 :::{tab-item} 🐍 Python
@@ -233,7 +233,7 @@ RXNS, METS, COMPS, GENES, MODEL
 
 `exportToExcelFormat` writes `.xlsx` and errors on any other extension, so a
 bare directory path is rejected rather than interpreted. The
-[RAVEN 3 migration guide](../raven3-migration.md#excel-io) covers scripts
+[RAVEN 3 migration guide](../raven3-migration/formats-and-reconstruction.md#excel-io) covers scripts
 that pass one. There is no matching importer: `curateModelFromTables` reads
 a curated spreadsheet back by applying tabular edits to an existing model,
 not by building one from scratch.

docs/index.md

@@ -6,7 +6,7 @@
 **Reconstruction, Analysis and Visualization of Metabolic Networks**
 
 A toolkit for building, curating, and simulating genome-scale metabolic
-models, available as a MATLAB toolbox and a Python package built on cobrapy.
+models, available as a **MATLAB** toolbox and a **Python** package built on cobrapy.
 
 ## Install
 
@@ -20,6 +20,7 @@ pip install --pre raven-toolbox
 :::{tab-item} MATLAB (Add-Ons)
 
 Home → Add-Ons → Get Add-Ons → search "RAVEN Toolbox".
+
 Then run `checkRaven` to verify.
 :::
 :::{tab-item} Python (git)
@@ -143,7 +144,7 @@ Complete function reference for both MATLAB and Python.
 Set up RAVEN in MATLAB or raven-toolbox in Python with a solver.
 :::
 
-:::{grid-item-card} RAVEN and raven-toolbox
+:::{grid-item-card} RAVEN vs. raven-toolbox
 :link: raven3-vs-raven-toolbox
 :link-type: doc
 

docs/installation/raven.md

@@ -73,16 +73,25 @@ setRavenSolver('cobra');
 
 `ravenCobraWrapper` converts a model between the RAVEN struct and the COBRA
 Toolbox structure; see
-[RAVEN 3 and raven-toolbox](../raven3-vs-raven-toolbox.md#solvers).
+[RAVEN vs. raven-toolbox](../raven3-vs-raven-toolbox.md#solvers).
 
 ---
 
 ## Install
 
+:::{warning} Getting 3.0.0b1 specifically
+This site documents RAVEN **3.0.0b1**, a pre-release. Both the **Add-Ons
+manager** and the **Release download**'s normal releases page only offer the
+latest stable release (RAVEN 2.x), not 3.0.0b1: neither method can install
+what this site documents. Use the **Clone with git** tab, or the direct
+archive link in the **Release download** tab below.
+:::
+
 ::::{tab-set}
 :::{tab-item} {octicon}`plug;1em` Add-Ons manager
 
-Installs from within MATLAB, with no separate download.
+Installs from within MATLAB, with no separate download. **Installs the
+latest stable release, not 3.0.0b1**; see the warning above.
 
 1. Open the **Home** tab and click **Add-Ons → Get Add-Ons**.
 2. Search for **RAVEN Toolbox** and click **Add → Add to MATLAB**.
@@ -93,20 +102,29 @@ If MATLAB does not pick up the toolbox after step 2, run
 :::
 :::{tab-item} {octicon}`download;1em` Release download
 
-Good for offline or managed environments.
+Good for offline or managed environments. **The
+[RAVEN releases page](https://github.com/SysBioChalmers/RAVEN/releases)
+itself only lists stable releases**; 3.0.0b1 is a git tag with no packaged
+release, so download it directly instead:
 
-1. Download the latest ZIP from the
-   [RAVEN releases page](https://github.com/SysBioChalmers/RAVEN/releases).
+1. Download
+   [the 3.0.0b1 archive](https://github.com/SysBioChalmers/RAVEN/archive/refs/tags/3.0.0b1.zip)
+   directly (this works without git).
 2. Extract it to a location of your choice.
 3. In MATLAB, add the RAVEN folder to the path (`pathtool`), then
    [verify](#verify).
 :::
 :::{tab-item} {octicon}`git-branch;1em` Clone with git
 
-Tracks the development branch, and upgrades with a single command.
+Clones the repository, then checks out the `3.0.0b1` tag specifically: a
+plain `git clone` alone tracks the `main` branch (stable RAVEN 2), not this
+site's pre-release.
 
 ```bash
 git clone --depth=1 https://github.com/SysBioChalmers/RAVEN.git
+cd RAVEN
+git fetch --depth=1 origin tag 3.0.0b1
+git checkout 3.0.0b1
 ```
 
 Add the folder to the MATLAB path and [verify](#verify).
@@ -185,11 +203,18 @@ release, and run `checkRaven`.
 :::
 :::{tab-item} {octicon}`git-branch;1em` Clone with git
 
+The `3.0.0b1` tag does not move, so there is nothing to pull while staying on
+it. To move past this site's documented snapshot onto the actively-developed
+branch:
+
 ```bash
-git pull origin main
+git checkout develop3
+git pull origin develop3
 ```
 
-Then run `checkRaven`.
+`develop3` can be ahead of what this page describes; see
+[RAVEN 2 to RAVEN 3](../raven3-migration.md) for what changed and when this
+document was last checked against it. Then run `checkRaven`.
 :::
 ::::
 

docs/parameter-tuning/index.md

@@ -100,18 +100,11 @@ cross-toolbox to-do list.
 |---|---|
 | [Parameter benchmarks](benchmarks.md) | `fseof`, `remove_genes`, `connect_blocked_reactions`, `fill_gaps_*`, `check_tasks`, `find_task_essential_reactions` |
 
-## Model file format
-
-[YAML model format](../yaml-format.md): the format cobrapy, raven-toolbox and
-RAVEN MATLAB all read and write, for moving a model file between any of them
-or into version control.
-
 ```{toctree}
 :hidden:
 
 ../tuned-parameters
 benchmarks
-../yaml-format
 ```
 
 ```{toctree}