edkerk · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026 · Sep 9, 2026
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -22,6 +22,28 @@
   border: 0;
 }
 
+/* ===== Tables: fit the article column instead of forcing a horizontal
+   scrollbar. table-layout:auto sizes a table from its content's preferred
+   width with no upper bound; capping it at the container's width makes long
+   cells wrap instead of pushing the table wider than the page. ============ */
+.bd-article table {
+  table-layout: fixed;
+  width: 100%;
+  max-width: 100%;
+}
+.bd-article table td,
+.bd-article table th {
+  overflow-wrap: break-word;
+}
+/* Sphinx wraps inline code in a single white-space:nowrap span, which is
+   right in prose but lets one long identifier list force a table cell wide.
+   Table cells are the one place breaking a code token mid-word is better
+   than the cell (and the whole table) overflowing. */
+.bd-article table code .pre {
+  white-space: normal;
+  overflow-wrap: break-word;
+}
+
 /* ===== Home page logo: swap for the dark scheme ======================= */
 .rh-logo-light, .rh-logo-dark {
   max-width: 420px;

diff --git a/docs/api/index.md b/docs/api/index.md
@@ -33,10 +33,10 @@ To move between the two implementations, use the **[MATLAB vs Python](../matlab-
 table, which pairs every function that exists in both (`camelCase` ↔ `snake_case`) and
 links to both references.
 
-## How the two line up
+## How the two compare
 
 The implementations are deliberately kept aligned. The main differences are
-mechanical:
+in calling convention, not in what the functions compute:
 
 | | RAVEN (MATLAB) | raven-toolbox (Python) |
 |---|---|---|

diff --git a/docs/guide/biomass.md b/docs/guide/biomass.md
@@ -14,7 +14,7 @@ annotation that makes a model interpretable to something other than a solver.
 | `scaleBiomassPseudoreaction` | `rescale_pseudoreaction` | rescale a pseudoreaction and rebalance it |
 | `assignSBOterms` | `add_sbo_terms` | label reactions and metabolites with SBO terms |
 | `loadDeltaGCSV`, `saveDeltaGCSV` | `load_delta_g_csv`, `save_delta_g_csv` | thermodynamic data through CSV |
-| `extractMiriam`, `editMiriam` | `Object.annotation` {bdg-secondary}`cobrapy` | read and edit database cross-references |
+| `extractMiriam`, `editMiriam` | `Object.annotation` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | read and edit database cross-references |
 
 ## Setup
 
@@ -176,9 +176,10 @@ representation.
 
 ## 22.2 Change one component
 
-Measured a different protein content? Set it, and say what gives way. A biomass
-that no longer sums to 1 is worse than one with the old number in it, so both
-functions can balance a second component to absorb the difference.
+Measured a different protein content? Set it, and specify which other component
+absorbs the change. A biomass that no longer sums to 1 is worse than one with the
+old number in it, so both functions can balance a second component to absorb the
+difference.
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB

diff --git a/docs/guide/building.md b/docs/guide/building.md
@@ -9,11 +9,11 @@ reconstruction is involved.
 
 | MATLAB | Python | |
 |---|---|---|
-| `addMets` | `Metabolite` {bdg-secondary}`cobrapy` | add metabolites |
+| `addMets` | `Metabolite` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | add metabolites |
 | `addRxns` | `add_reactions_from_equations` | add reactions from equation strings |
-| `addGenesRaven` | auto-created from the GPR {bdg-secondary}`cobrapy` | add genes |
-| `addExchangeRxns` | `Model.add_boundary` {bdg-secondary}`cobrapy` | add exchange reactions |
-| `constructEquations` | `Reaction.reaction` {bdg-secondary}`cobrapy` | read the equations back |
+| `addGenesRaven` | auto-created from the GPR {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | add genes |
+| `addExchangeRxns` | `Model.add_boundary` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | add exchange reactions |
+| `constructEquations` | `Reaction.reaction` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | read the equations back |
 
 The important part is the same in both: **write the reaction as an equation
 string** and let the toolbox derive the stoichiometry, rather than filling in a

diff --git a/docs/guide/combining.md b/docs/guide/combining.md
@@ -1,6 +1,7 @@
 # 16. Combining and simplifying models
 
-Two operations that look like bookkeeping and are not. **Merging** puts models
+This page covers two operations that look like simple bookkeeping but carry real
+risk. **Merging** puts models
 together: a draft and a template, two organisms, a curated core and an
 extension, and the result is only as sound as the assumption that a metabolite
 in one model is the same molecule as in the other. **Simplifying** takes a model
@@ -20,8 +21,8 @@ you needed.
 ## Setup
 
 `smallYeast.yml`, and a second model to merge it with. Taking a copy and giving
-it a new id keeps the example honest: whatever the merge does to two identical
-models is the clearest possible statement of what it matches on.
+it a new id makes the comparison unambiguous: whatever the merge does to two
+identical models is the clearest possible statement of what it matches on.
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB
@@ -114,7 +115,7 @@ way, without a warning.
 Matching on id is the right choice when both models come from the same
 database, where the ids mean the same thing and the names may not.
 
-:::{warning} Names, not identifiers
+:::{warning} Merging matches on names, not identifiers
 Two models built from different databases usually share almost no metabolite
 **names** either, in which case merging produces a model with two disconnected
 halves that happen to live in the same struct. Merging is a claim that the

diff --git a/docs/guide/comparing.md b/docs/guide/comparing.md
@@ -209,7 +209,8 @@ growth: good 0.1222, bad 0.0000
 The errors in `smallYeastBad` are not cosmetic. On the same medium, with the same
 objective, the good model grows and **the bad one does not grow at all**, from a
 model that a set-overlap score called 94.5 % similar. A diff tells you the models
-differ; only a simulation tells you what the difference costs. (MATLAB reports
+differ; only a simulation tells you what effect the difference has on growth.
+(MATLAB reports
 that zero as `-0.0000`; the minus sign is a formatting artefact of a zero
 objective, not a negative growth rate.)
 

diff --git a/docs/guide/deletions.md b/docs/guide/deletions.md
@@ -9,11 +9,11 @@ distribution better than plain FBA does".
 
 | MATLAB | Python | |
 |---|---|---|
-| `findGeneDeletions` | `single_gene_deletion` {bdg-secondary}`cobrapy` | knock out every gene in turn |
-| `findGeneDeletions` (`'sgd'`/`'dgd'`) | `double_gene_deletion` {bdg-secondary}`cobrapy` | pairs of genes |
-| `getEssentialRxns` | `find_task_essential_reactions` | reactions a task cannot do without |
+| `findGeneDeletions` | `single_gene_deletion` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | knock out every gene in turn |
+| `findGeneDeletions` (`'sgd'`/`'dgd'`) | `double_gene_deletion` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | pairs of genes |
+| `getEssentialRxns` | `find_task_essential_reactions` | reactions a task requires |
 | `deleteUnusedGenes` | `remove_genes` | remove genes, rather than knock them out |
-| no equivalent | `moma` {bdg-secondary}`cobrapy` | a knockout's fluxes, staying near the wild type |
+| no equivalent | `moma` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | a knockout's fluxes, staying near the wild type |
 
 ## Setup
 
@@ -152,7 +152,8 @@ because the same function shape serves the double-deletion case.
 ## 11.3 Essential reactions
 
 Reaction essentiality asks the same question one level down. The two functions
-below look equivalent and are not, which is why their answers differ by 24.
+below look equivalent but ask different questions, which is why their answers
+differ by 24.
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB
@@ -204,8 +205,8 @@ raven-toolbox has `find_task_essential_reactions`; see
 ## 11.4 Two at a time
 
 Double deletions find the redundancy single deletions miss: two genes that each
-look dispensable but cannot both go. The cost is quadratic in the number of
-genes, so run time grows sharply with model size.
+look dispensable but cannot both be deleted. The number of pairs to test is
+quadratic in the number of genes, so run time grows sharply with model size.
 
 ::::{tab-set}
 :::{tab-item} Ⓜ️ MATLAB

diff --git a/docs/guide/editing.md b/docs/guide/editing.md
@@ -11,8 +11,8 @@ page is the safe way to do each of those.
 | `changeRxns` | `change_reaction_equations` | replace a reaction's stoichiometry |
 | `changeGrRules` | `change_gene_reaction_rules` | set or extend gene associations |
 | `standardizeGrRules` | `gpr_to_dnf` | normalise a GPR |
-| `setParam` | `Reaction.bounds` {bdg-secondary}`cobrapy` | change bounds, objective |
-| `removeReactions` | `Model.remove_reactions` {bdg-secondary}`cobrapy` | delete reactions |
+| `setParam` | `Reaction.bounds` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | change bounds, objective |
+| `removeReactions` | `Model.remove_reactions` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | delete reactions |
 | `removeMets` | `remove_metabolites` | delete metabolites |
 | `removeGenes`, `deleteUnusedGenes` | `remove_genes` | delete genes |
 
@@ -250,7 +250,7 @@ with model:
 ```
 
 `remove_orphans=True` is cobrapy's equivalent of those two flags. Note the
-`with model:`, deletions inside it are rolled back on exit, so the cost of
+`with model:`, deletions inside it are rolled back on exit, so the effect of
 a deletion can be measured without keeping it.
 :::
 ::::

diff --git a/docs/guide/engineering.md b/docs/guide/engineering.md
@@ -1,9 +1,10 @@
 # 20. Engineering targets
 
-Two questions sit behind most strain-design work. Which reactions would have to
-change for the cell to make more of something, and which metabolites sit at the
-centre of a transcriptional response. FSEOF answers the first from stoichiometry
-alone; reporter metabolites answer the second from expression data.
+Two questions underlie most strain-design work. Which reactions would have to
+change for the cell to make more of something, and which metabolites are most
+affected by a transcriptional response. FSEOF answers the first from
+stoichiometry alone; reporter metabolites answer the second from expression
+data.
 
 ### Functions on this page
 
@@ -132,7 +133,7 @@ zero.
 
 ## 20.2 Reading the scan
 
-A target is only as good as the trend behind it. The scan matrix is what
+A target's reliability depends on the trend behind it. The scan matrix is what
 distinguishes a reaction that rises steadily from one that jumps once and stops.
 
 ::::{tab-set}
@@ -289,8 +290,8 @@ above.
   nothing is differentially expressed. Look at the input distribution before
   trusting the ranking.
 - **Currency metabolites at the top.** ATP, NADH and water take part in a
-  large share of all reactions, so they surface easily. Excluding them, or
-  reading past them, is usually necessary.
+  large share of all reactions, so they appear at the top easily. Excluding
+  them, or reading past them, is usually necessary.
 :::
 
 ## See also

diff --git a/docs/guide/fba.md b/docs/guide/fba.md
@@ -7,21 +7,21 @@ This is the loop every other analysis on this site is built from.
 
 | MATLAB | Python | |
 |---|---|---|
-| `setParam` | `Reaction.bounds`, `Model.objective` {bdg-secondary}`cobrapy` | set bounds and the objective |
-| `solveLP` | `Model.optimize` {bdg-secondary}`cobrapy` | solve the LP |
-| `printFluxes` | `Model.summary` {bdg-secondary}`cobrapy` | show the fluxes that carry material |
-| `solveLP` (`minFlux`) | `pfba` {bdg-secondary}`cobrapy` | pick a parsimonious solution among the optima |
+| `setParam` | `Reaction.bounds`, `Model.objective` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | set bounds and the objective |
+| `solveLP` | `Model.optimize` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | solve the LP |
+| `printFluxes` | `Model.summary` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | show the fluxes that carry material |
+| `solveLP` (`minFlux`) | `pfba` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | pick a parsimonious solution among the optima |
 
 :::{admonition} Where the Python functions come from
 :class: info
 Every simulation step on this page is cobrapy, marked
-{bdg-secondary}`cobrapy` in the table above. In MATLAB,
+{bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` in the table above. In MATLAB,
 `solveLP` needs neither the COBRA Toolbox nor anything else outside RAVEN.
 :::
 
 ## Setup
 
-`yeast-GEM.xml` from [`docs/data/`](../data/README.md), yeast-GEM v9.1.0, which
+`yeast-GEM.yml` from [`docs/data/`](../data/README.md), yeast-GEM v9.1.0, which
 arrives with a growth objective and an aerobic glucose medium already set.
 
 ## 4.1 Solve
@@ -31,25 +31,21 @@ arrives with a growth objective and an aerobic glucose medium already set.
 :sync: matlab
 
 ```matlab
-model = importModel('yeast-GEM.xml');
+model = readYAMLmodel('yeast-GEM.yml');
 sol = solveLP(model);
 fprintf('objective: %s\n', model.rxns{model.c == 1});
 fprintf('status:    %d\n', sol.stat);
 fprintf('growth:    %.4f /h\n', sol.f);
 ```
 
 ```text
-[Warning: The following fields have prefixes removed from all entries. If this is undesired, run importModel with removePrefix as false. Example: importModel('filename.xml',[],false);]
-[Warning: The following MIRIAM strings are associated to more than one unique metabolite name: bigg.metabolite/ficytb5 bigg.metabolite/hdd2coa bigg.metabolite/pail_cho bigg.metabolite/pchol_cho bigg.metabolite/succ bigg.metabolite/tchola chebi/CHEBI:138108 chebi/CHEBI:17140 chebi/CHEBI:18097 ...and 23 more]
 objective: r_2111
 status:    1
 growth:    0.0809 /h
 ```
 
 The objective is `model.c`, a vector with one entry per reaction, so
-`model.c == 1` finds the reaction being maximised. The two warnings come from
-the reader, not the solve; [3. Reading and writing models](io.md) explains
-both.
+`model.c == 1` finds the reaction being maximised.
 
 `sol` carries the whole answer. `sol.f` is the objective value with its
 natural sign: RAVEN minimises internally and negates the result, so no sign
@@ -72,9 +68,9 @@ LP dual.
 :sync: python
 
 ```python
-from cobra.io import read_sbml_model
+from raven_toolbox.io import read_yaml_model
 
-model = read_sbml_model("yeast-GEM.xml")
+model = read_yaml_model("yeast-GEM.yml")
 solution = model.optimize()
 
 print(f"objective: {model.objective.expression}")
@@ -344,7 +340,7 @@ total flux: 100.6
 ```
 
 `minFlux` selects the second optimisation. `1` minimises the sum of absolute
-fluxes, which costs one further LP. `3`
+fluxes, which requires one further LP. `3`
 minimises the *number* of active reactions instead, which is a
 mixed-integer problem: the result is easier to read as a pathway, and the
 solve is far slower. Leaving `minFlux` at `0` skips the second solve

diff --git a/docs/guide/fva.md b/docs/guide/fva.md
@@ -1,19 +1,19 @@
 # 14. Flux variability and alternative optima
 
 An FBA solution is one point in a space of equally optimal answers. Flux
-variability asks the more honest question: **given the objective, how much can
-each reaction's flux still vary?** It is how you tell a flux the model insists on
-from one it merely happened to report.
+variability asks the more accurate question: **given the objective, how much can
+each reaction's flux still vary?** It is how you distinguish a flux the model
+requires from one it merely happened to report.
 
 ### Functions on this page
 
 | MATLAB | Python | |
 |---|---|---|
-| `getAllowedBounds` | `flux_variability_analysis` {bdg-secondary}`cobrapy` | the range each reaction can take |
-| `haveFlux` | `find_blocked_reactions` {bdg-secondary}`cobrapy` | reactions that can carry no flux at all |
-| `solveLP` (`minFlux`) | `pfba` {bdg-secondary}`cobrapy` | one representative optimum |
-| no equivalent | `loopless_solution` {bdg-secondary}`cobrapy` | an optimum without thermodynamically infeasible loops |
-| no equivalent | `add_loopless` {bdg-secondary}`cobrapy` | the constraints behind `loopless="fastSNP"` |
+| `getAllowedBounds` | `flux_variability_analysis` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | the range each reaction can take |
+| `haveFlux` | `find_blocked_reactions` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | reactions that can carry no flux at all |
+| `solveLP` (`minFlux`) | `pfba` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | one representative optimum |
+| no equivalent | `loopless_solution` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | an optimum without thermodynamically infeasible loops |
+| no equivalent | `add_loopless` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | the constraints behind `loopless="fastSNP"` |
 | no equivalent | `find_good_reactions` | reactions whose range is real rather than a loop |
 
 ## Setup
@@ -149,7 +149,7 @@ land on.
 
 ## 14.3 A wide range is not always a real one
 
-A reaction can show a wide range purely because it sits in a thermodynamically
+A reaction can show a wide range purely because it is part of a thermodynamically
 infeasible cycle, flux going round a loop with no net driving force. The widest
 span in 14.1 was 1000, the model's default bound. That span is such a cycle.
 
@@ -242,7 +242,7 @@ growth: 0.1222 /h, total flux: 20.9
 
 `minFlux` minimises total absolute flux subject to the objective, which is
 parsimonious FBA. It is also the closest RAVEN gets to excluding loops: a
-cycle costs flux, so a parsimonious solution has no reason to carry one.
+cycle adds flux, so a parsimonious solution has no reason to carry one.
 :::
 :::{tab-item} 🐍 Python
 :sync: python

diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
@@ -8,11 +8,11 @@ gene. Every later page assumes these operations.
 | MATLAB | Python | |
 |---|---|---|
 | `readYAMLmodel` | `read_yaml_model` | read a RAVEN YAML model |
-| `importModel` | `read_sbml_model` {bdg-secondary}`cobrapy` | read an SBML model |
-| `printModelStats` | model attributes {bdg-secondary}`cobrapy` | how big the model is |
-| `getIndexes` | `get_by_id` {bdg-secondary}`cobrapy` | look something up by identifier |
-| `constructEquations` | `Reaction.reaction` {bdg-secondary}`cobrapy` | a reaction as a readable string |
-| `getElementalBalance` | `check_mass_balance` {bdg-secondary}`cobrapy` | is a reaction balanced |
+| `importModel` | `read_sbml_model` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | read an SBML model |
+| `printModelStats` | model attributes {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | how big the model is |
+| `getIndexes` | `get_by_id` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | look something up by identifier |
+| `constructEquations` | `Reaction.reaction` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | a reaction as a readable string |
+| `getElementalBalance` | `check_mass_balance` {bdg-link-secondary}`cobrapy <https://cobrapy.readthedocs.io/en/latest/autoapi/cobra/index.html>` | is a reaction balanced |
 
 ## Setup
 
@@ -336,7 +336,7 @@ decide, so an empty result covers both "balanced" and "nothing to check".
 
 ## See also
 
-- [User guide overview](index.md), the other pages, and what is still planned.
+- [Guide overview](index.md), the other pages, and what is still planned.
 - [MATLAB vs Python](../raven3-vs-raven-toolbox.md), what each toolbox has, and where
   cobrapy takes over.
 - [API reference](../api/index.md), every function in both toolboxes.