Repository navigation
Site-wide documentation polish: titles, prose, and installation coverage - #81
Merged
Merged
Conversation
…ation guide
Small batch of feedback after the pydata-sphinx-theme switch.
- index.md: the pip install had no --pre, so it would refuse to install
the current 3.0.0b1 pre-release; the MATLAB installs never mentioned
checkRaven to verify.
- migrate.md / parameter-tuning/index.md: the YAML model format page was
filed under Migrate, but it is a file-format reference, not a
version/language migration; moved it under Methods.
- raven3-vs-raven-toolbox.md: "Confidence tracking" and the newer
assignCompartments were listed as shipped raven-toolbox-only
capabilities; both are still WIP. "Scope: reconstruction and analysis"
was filed under "What only RAVEN has", but it describes ground RAVEN and
raven-toolbox share against the COBRA Toolbox, not a RAVEN-only capability.
- raven3-migration.md: no summary at the top for a reader who reads
nothing else. Several headings carried a leftover MkDocs-style
<a name="..."> anchor with no href; pydata-sphinx-theme's sidebar-toggle
script iterates every in-page anchor and calls getAttribute("href").startsWith(...)
on each, so the null href threw and aborted the rest of the script's
init, including the collapse-sidebar button's own click handler, on this
page only. Several of those anchor names also didn't match MyST's
auto-generated heading id (kegg-reconstruction, sbml-io, excel-io, and
others), which is why guide/io.md's links into this page were already
warning at build time.
- _static/custom.css: tables have no upper bound on width under
table-layout: auto, and one long comma-separated identifier list
rendered as a single non-wrapping .pre span was enough to force a table
to nearly twice the width of the article column.
Two rounds of feedback: a site-wide sweep for idiomatic and headline-style
phrasing (many readers are non-native English speakers), and a batch of
title, content, and factual fixes.
- CLAUDE.md (new): documents the no-idiom/no-headline-fragment prose rule
for future edits, with the two flagged examples.
- Site-wide sweep: dozens of headings and sentences across docs/guide/,
docs/parameter-tuning/, docs/protocol/, docs/tutorials/, and the
top-level pages relied on implied grammar or figurative language ("same
verdicts, very different cost", "the cost of a deletion", "a gold
standard", "showed its age", "drift apart") instead of stating the point
directly.
- docs/guide/index.md, docs/index.md, docs/parameter-tuning/index.md,
docs/references.md: "User guide", "Methods", and "References" named the
tab by category instead of content; renamed to "Guide", "Parameter
tuning", and "Citations". The Guide's own sidebar captions ("Install",
"Functions") had the same problem; renamed to "Installation" and "Task
pages".
- docs/guide/fba.md, docs/guide/media.md: loaded yeast-GEM.xml over SBML
when the same model already ships as yeast-GEM.yml, needing an extra
import path and printing two SBML-reader warnings unrelated to either
page's actual topic.
- docs/raven3-vs-raven-toolbox.md: the "What identical results means"
section restated general MILP/statistical-comparison background already
covered elsewhere on the page; removed. The elemental balance
explanation didn't say what "balanced" means or why the unknown case
matters; rewritten. The solvers table said MATLAB's GLPK comes via the
COBRA Toolbox; it ships bundled with RAVEN itself.
- docs/installation/raven.md: solver setup (Gurobi license/savepath, COBRA
Toolbox integration, setRavenSolver's valid values), the
addRavenToUserPath fallback for managed installs, and
checkInstallation's rename to checkRaven were all on the RAVEN wiki's
installation page but missing here; added. Two headings used an inline
"{ #id }" attribute the site's Markdown flavor doesn't support, so the
ids never applied and three "verify the installation" links pointed at
nothing; fixed to real anchors.
- scripts/gen_api_pages_sphinx.py, docs/matlab-vs-python.md: the
cobrapy-covered functions sat in a separate, badge-less section instead
of the main pairs table; merged in, marked with a linked cobrapy badge.
guide/index.md's own admonition already claimed the badge links to the
cobrapy documentation, but the plain {bdg-secondary} role used across all
14 guide pages has no href; only the new matlab-vs-python.md badge did.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up feedback after the pydata-sphinx-theme switch: install steps, page titles, a prose-clarity sweep, and installation coverage pulled from the RAVEN wiki.
docs/index.md: the pip install had no--pre, so it would refuse to install the current 3.0.0b1 pre-release; the MATLAB installs never mentionedcheckRaven.docs/migrate.md/docs/parameter-tuning/: the YAML model format page was filed under Migrate, but it is a file-format reference, not a version/language migration.docs/raven3-vs-raven-toolbox.md: "Confidence tracking" and the newerassignCompartmentswere listed as shipped raven-toolbox-only capabilities, both still WIP; "Scope: reconstruction and analysis" was filed under "What only RAVEN has" but describes ground both toolboxes share against the COBRA Toolbox; the elemental balance explanation never said what "balanced" means or why theunknowncase matters; "What identical results means" restated background covered elsewhere on the page; the solvers table said MATLAB's GLPK comes via the COBRA Toolbox, when it ships bundled with RAVEN itself.docs/raven3-migration.md: leftover MkDocs-style<a name="...">anchors with nohrefmade pydata-sphinx-theme's sidebar-toggle script throw on this page only, breaking the collapse-sidebar button; several tables had no upper bound on width undertable-layout: autoand could reach twice the article column's width.docs/guide/,docs/parameter-tuning/,docs/protocol/,docs/tutorials/, and the top-level pages: dozens of headings and sentences relied on implied grammar or figurative language ("same verdicts, very different cost", "a gold standard", "showed its age", "drift apart") instead of stating the point directly;CLAUDE.md(new) documents the rule for future edits.docs/guide/index.md,docs/index.md,docs/parameter-tuning/index.md,docs/references.md: "User guide", "Methods", and "References" named the tab by category instead of content; renamed to "Guide", "Parameter tuning", and "Citations".docs/guide/fba.md,docs/guide/media.md: loadedyeast-GEM.xmlover SBML when the same model already ships asyeast-GEM.yml.docs/installation/raven.md: solver setup (Gurobi license/savepath, COBRA Toolbox integration,setRavenSolver's valid values), theaddRavenToUserPathfallback for managed installs, and thecheckInstallationtocheckRavenrename were on the RAVEN wiki's installation page but missing here. Two headings used an inline{ #id }attribute this site's Markdown flavor doesn't support, so three "verify the installation" links pointed at nothing.scripts/gen_api_pages_sphinx.py,docs/matlab-vs-python.md: cobrapy-covered functions sat in a separate, badge-less section instead of the main pairs table.docs/guide/*.md: the cobrapy badge was described as linking to cobrapy's docs, but used a non-linking badge role everywhere except the regenerated table.Full rebuild: 0 errors, 25 warnings (down from 66 before this branch), all pre-existing and unrelated.