Skip to content

Regroup the task pages, retire the legacy protocol's RAVEN 2 framing, and more installation/title fixes - #82

Merged
edkerk merged 1 commit into
mainfrom
docs/task-page-reorg
Sep 9, 2026
Merged

edkerk merged 1 commit into
mainfrom
docs/task-page-reorg

Conversation

@edkerk

@edkerk edkerk commented Sep 9, 2026 •

Copy link
Copy Markdown
Collaborator

Third round of feedback on the pydata-sphinx-theme site.

  • docs/guide/index.md and the 22 task pages: three reconstruction methods
    (homology, KEGG, context-specific models) were split across two different
    section headings, with two of them stranded under "Analysis and repair"
    alongside curation and biomass pages that are really about building and
    curating a model, not analysing one. Regrouped into Foundations,
    Simulation, Building and curating, Reconstruction, Analysis and repair,
    and Comparing and engineering, renumbered 1-22 throughout (headings,
    subsection numbers, and every cross-reference site-wide), and swapped
    Deletions and Metabolic tasks within that order. Item 14's list entry
    dropped "tINIT" from its title; the page's own tINIT-vs-ftINIT comparison
    is unchanged.
  • docs/protocol/: "Worked protocol" described the page's role, not its
    content. Renamed to "GEM reconstruction protocol", numbered subsections
    (leftover from the source paper's own section numbers) dropped since nothing
    else on the site uses them, and an info box added stating the original
    published protocol is RAVEN 2 and this site applies minor modifications for
    RAVEN 3. Dropped anticipated-results.md, which repeated content already on
    simulation.md's output. Legacy protocol and legacy tutorials were two
    separate sidebar sections for what both introductions already call one
    category; merged into a single "Legacy" section.
  • docs/installation/raven.md, docs/guide/solvers.md, docs/tutorials/index.md:
    checkInstallation was renamed to checkRaven in RAVEN 3 (checkInstallation
    survives only as a deprecated forwarding wrapper); these still called it by
    the old name. The sample checkRaven output on the installation page was
    also the old checkInstallation's simpler format, not what checkRaven
    actually prints (verified against the function's current source).
  • docs/tutorials/index.md: tutorials 2-4 depend on importExcelModel, which
    RAVEN 3 removed outright with no forwarding wrapper; nothing on the page
    said the Excel-editing step no longer runs as written.
  • docs/installation/data-and-binaries.md: renamed to "Download data and
    binaries" (its own contents are download instructions, not a record of
    what has already been downloaded). "Where it goes" gave one cache path
    and called it universal, when raven-toolbox's cache directory resolves to
    a different absolute path on each OS; added the three real paths,
    verified against raven-toolbox's own cache-path source, each on its own
    tab. Dropped "Integrity and versions" and "Licences", which repeated
    general package-management background unrelated to this site's own setup
    steps.
  • docs/raven3-vs-raven-toolbox.md: the solvers table said MATLAB's GLPK
    comes via the COBRA Toolbox; it ships bundled with RAVEN itself, no COBRA
    Toolbox involved. "Moving a model between them" and "Coming from RAVEN 2.0
    to Python" repeated the YAML/SBML interoperability and RAVEN-2-specific
    background covered in more depth on yaml-format.md and
    raven3-migration.md respectively. Retitled to "RAVEN and raven-toolbox"
    (RAVEN 3 is the only supported line now) and added an early pointer to the
    MATLAB vs Python table for readers looking for one specific function.
  • docs/raven3-migration.md: retitled to "RAVEN 2 to RAVEN 3" for the same
    reason.
  • docs/matlab-vs-python.md, docs/api/index.md, docs/migrate.md: the mapping
    table is a function reference, not a migration path; moved it from under
    Migrate to under API reference.
  • docs/references.md: the INIT and ftINIT citations sat under one heading
    with a note explaining they were different papers; split into their own
    "ftINIT" and "tINIT" subsections so each is under its own citation.
  • docs/index.md: the MATLAB (Add-Ons) install step ran its two instructions
    into one paragraph; split onto separate lines. The Python (git) install
    cloned the full history where the MATLAB (git) tab already used
    --depth=1.

… and more installation/title fixes

Third round of feedback on the pydata-sphinx-theme site.

- docs/guide/index.md and the 22 task pages: three reconstruction methods
  (homology, KEGG, context-specific models) were split across two different
  section headings, with two of them stranded under "Analysis and repair"
  alongside curation and biomass pages that are really about building and
  curating a model, not analysing one. Regrouped into Foundations,
  Simulation, Building and curating, Reconstruction, Analysis and repair,
  and Comparing and engineering, renumbered 1-22 throughout (headings,
  subsection numbers, and every cross-reference site-wide), and swapped
  Deletions and Metabolic tasks within that order. Item 14's list entry
  dropped "tINIT" from its title; the page's own tINIT-vs-ftINIT comparison
  is unchanged.
- docs/protocol/: "Worked protocol" described the page's role, not its
  content. Renamed to "GEM reconstruction protocol", numbered subsections
  (leftover from the source paper's own section numbers) dropped since nothing
  else on the site uses them, and an info box added stating the original
  published protocol is RAVEN 2 and this site applies minor modifications for
  RAVEN 3. Dropped anticipated-results.md, which repeated content already on
  simulation.md's output. Legacy protocol and legacy tutorials were two
  separate sidebar sections for what both introductions already call one
  category; merged into a single "Legacy" section.
- docs/installation/raven.md, docs/guide/solvers.md, docs/tutorials/index.md:
  checkInstallation was renamed to checkRaven in RAVEN 3 (checkInstallation
  survives only as a deprecated forwarding wrapper); these still called it by
  the old name. The sample checkRaven output on the installation page was
  also the old checkInstallation's simpler format, not what checkRaven
  actually prints (verified against the function's current source).
- docs/tutorials/index.md: tutorials 2-4 depend on importExcelModel, which
  RAVEN 3 removed outright with no forwarding wrapper; nothing on the page
  said the Excel-editing step no longer runs as written.
- docs/installation/data-and-binaries.md: renamed to "Download data and
  binaries" (its own contents are download instructions, not a record of
  what has already been downloaded). "Where it goes" gave one cache path
  and called it universal, when raven-toolbox's cache directory resolves to
  a different absolute path on each OS; added the three real paths,
  verified against raven-toolbox's own cache-path source, each on its own
  tab. Dropped "Integrity and versions" and "Licences", which repeated
  general package-management background unrelated to this site's own setup
  steps.
- docs/raven3-vs-raven-toolbox.md: the solvers table said MATLAB's GLPK
  comes via the COBRA Toolbox; it ships bundled with RAVEN itself, no COBRA
  Toolbox involved. "Moving a model between them" and "Coming from RAVEN 2.0
  to Python" repeated the YAML/SBML interoperability and RAVEN-2-specific
  background covered in more depth on yaml-format.md and
  raven3-migration.md respectively. Retitled to "RAVEN and raven-toolbox"
  (RAVEN 3 is the only supported line now) and added an early pointer to the
  MATLAB vs Python table for readers looking for one specific function.
- docs/raven3-migration.md: retitled to "RAVEN 2 to RAVEN 3" for the same
  reason.
- docs/matlab-vs-python.md, docs/api/index.md, docs/migrate.md: the mapping
  table is a function reference, not a migration path; moved it from under
  Migrate to under API reference.
- docs/references.md: the INIT and ftINIT citations sat under one heading
  with a note explaining they were different papers; split into their own
  "ftINIT" and "tINIT" subsections so each is under its own citation.
- docs/index.md: the MATLAB (Add-Ons) install step ran its two instructions
  into one paragraph; split onto separate lines. The Python (git) install
  cloned the full history where the MATLAB (git) tab already used
  --depth=1.
@edkerk
edkerk merged commit 8789ad2 into main Sep 9, 2026
2 checks passed
@edkerk
edkerk deleted the docs/task-page-reorg branch September 9, 2026 19:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant