Address the RAVEN 3 Guide review by edkerk · Pull Request #89 · CompMetEng/raven-docs

edkerk · 2026-10-17T19:32:45Z

Addresses the RAVEN 3 Guide review (comments G01–G30).

The RAVEN and raven-toolbox submodules point at their develop heads, which include CompMetEng/RAVEN#7 and CompMetEng/raven-toolbox#175; the documented outputs come from that code.

Example checks

scripts/run_examples.py compares each example with the plain ```text block below it, and --update writes that form. The examples workflow also runs on RAVEN changes.
The MATLAB MILP examples run on GLPK, showing RAVEN's warning that recommends Gurobi; the Python job needs no Gurobi licence.

Guide

Every section the review flagged is rewritten to match what the code does: FBA, FVA, sampling, MOMA (quadratic, on a viable knockout), media, solvers, quality control, gap filling, tasks, curation, biomass, I/O, model structure, homology, KEGG, comparing models and engineering.
Gap filling: gapFillMILP and fill_gaps_milp only add reactions; the infeasible-model error of gapReport and gap_report is described.
Every example data file is listed, with how to run a page; the README and build notes describe the Sphinx build.

Reference

On the guide pages, function names link to their API entry: RAVEN and raven-toolbox names to the generated reference, cobrapy names to cobrapy's documentation through intersphinx. The "Functions on this page" tables link every entry, prose links the first mention per section, and cobrapy badges point at the named function.
The API reference renders numpydoc help as MyST.
The tutorials include their scripts from RAVEN's tutorials/ folder.
Pages describe RAVEN 3 and its develop branch; the RAVEN 2 → 3 pages compare RAVEN 2.11.3 with RAVEN 3.

Build

The MkDocs files are removed; the Sphinx build uses requirements.txt and scripts/gen_api_pages.py, and scripts/check_names.py runs on its own.

The MyST pages mark expected output with a bare text fence; the runner only recognised the old title="Output" fence and so compared nothing. Also trigger the examples workflow on RAVEN submodule changes.

…al repair

…jectives

…MOMA

…close every boundary

… files

…does

…name[comp]

…oded

… and charge

… SBO rules

… the cost and mean bullets

…e flux vector

…oxes

RAVEN solves MILPs with its bundled GLPK and warns that Gurobi is faster, so the gap-filling and minimal-medium examples no longer need Gurobi. Fill in the curation outputs from the fixed curation functions.

The site is built with Sphinx. mkdocs.yml, its hooks, the mkdocs-gen-files generator, the Material icons and stylesheet, and the one-time migration scripts go; requirements-sphinx.txt and gen_api_pages_sphinx.py take the plain names, and check_names.py is a standalone check.

read-the-docs-community · 2026-10-17T22:11:51Z

Documentation build overview

📚 raven-docs | 🛠️ Build #35339823 | 📁 Comparing 0dde30a against latest (e3feefe)

🔍 Preview build

96 files changed · ± 96 modified

± Modified

scripts/autolink.py rewrites the inline code spans of the guide pages at build time: RAVEN and raven-toolbox names link to their entries in the generated API pages, cobrapy names to cobrapy's documentation through its intersphinx inventory. Every name in a table row is linked, and the first mention per section in the prose; the cobrapy badge in a table row points at the object in that row.

# Conflicts: # RAVEN # raven-toolbox

edkerk force-pushed the fix/guide-review branch from 1d48cfc to b4efe4b Compare October 17, 2026 20:15

edkerk added 29 commits October 18, 2026 00:10

fix: compare guide examples with their plain text output blocks

4420118

The MyST pages mark expected output with a bare text fence; the runner only recognised the old title="Output" fence and so compared nothing. Also trigger the examples workflow on RAVEN submodule changes.

docs: describe what the guide examples workflow runs and checks

79ce7e7

docs(kegg): state the toolbox version behind the quoted numbers

e25fd60

docs(tasks): run tasks against a closed boundary and fix the growth task

92f58e6

docs(solvers): describe MILPs on GLPK in both toolboxes and the QP case

29e4972

docs(gap-filling): call both connectivity fillers MILPs and show a re…

b13adde

…al repair

docs(media): scope the uptake sign and describe the minimal-medium ob…

db6d7d0

…jectives

docs(deletions): use a viable knockout and a wild-type reference for …

ba5307b

…MOMA

docs(quality-control): scope blocked reactions to current bounds and …

15a0347

…close every boundary

docs: say what flux a model without exchanges can still carry

2cc26ec

docs(homology): count BLAST alignments, not genes, and link the FASTA…

1479b4b

… files

docs(fba): scope the uptake sign and list what the context manager un…

4029adb

…does

docs(model-structure): pair getIndexes with an id lookup and resolve …

c05abb7

…name[comp]

docs(io): cobrapy decodes entity ids and leaves only the model id enc…

65926ec

…oded

docs(curation): read the table by header and use a consistent formula…

a988ca8

… and charge

docs(biomass): balance to 1 g/gDW, read SBO terms back, and state the…

3e1231b

… SBO rules

docs(fva): compare ranges at the optimum and with a 90% growth floor

ee4e3e8

docs(sampling): attribute chain differences to the warmup LPs and fix…

8f611a3

… the cost and mean bullets

docs(comparing): compare behaviour by growth, ranges or tasks, not on…

3ae2015

…e flux vector

docs(engineering): reporter metabolite scores agree between the toolb…

a714671

…oxes

docs: list every example data file and say how to run a page

be96334

docs: describe the Sphinx build in the README and build notes

6bbea6f

docs(tutorials): include the scripts from RAVEN's tutorials folder

7728856

feat: render numpydoc help as MyST in the API reference

21f1b6b

docs(guide): run the MATLAB MILP examples on GLPK

28f7e16

RAVEN solves MILPs with its bundled GLPK and warns that Gurobi is faster, so the gap-filling and minimal-medium examples no longer need Gurobi. Fill in the curation outputs from the fixed curation functions.

docs(guide): follow the corrected curateModelFromTables warning

2bb7201

Gap-filling MILP without reversal; gap_report infeasibility error

28e024a

fill_gaps_kumar_milp is now fill_gaps_milp

43f098b

docs: describe RAVEN 3 and its develop branch, not develop3

d6359b9

edkerk added 2 commits October 18, 2026 00:10

chore: update RAVEN and raven-toolbox to develop

6730248

edkerk force-pushed the fix/guide-review branch from 42e01f5 to 6730248 Compare October 17, 2026 22:10

edkerk added 2 commits October 18, 2026 00:41

Merge remote-tracking branch 'origin/main' into pr89-merge

0dde30a

# Conflicts: # RAVEN # raven-toolbox

edkerk merged commit 735c9ea into main Oct 22, 2026
3 checks passed

edkerk deleted the fix/guide-review branch October 22, 2026 23:30

Navigation Menu

Repository navigation

Address the RAVEN 3 Guide review - #89

Address the RAVEN 3 Guide review#89
edkerk merged 33 commits into
mainfrom
fix/guide-review

edkerk commented Oct 17, 2026 •

edited

Loading

Uh oh!

read-the-docs-community Bot commented Oct 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

edkerk commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

edkerk commented Oct 17, 2026 •

edited

Loading

read-the-docs-community Bot commented Oct 17, 2026 •

edited

Loading