Put the user guide and API first in the navigation - #47
Merged
Conversation
The header tabs read Home, Installation, MATLAB vs Python, Parameter tuning, Guides, API documentation, References -- so the two things people come here to use were fifth and sixth, behind a 21-page section of calibration studies that exists to justify defaults rather than to be read. The guide's pages sat three levels deep, at Guides > User guide > page. Tabs are now Home, User guide, API reference, MATLAB vs Python, Parameter tuning, References. Six instead of seven, with the guide second and the API third, and every guide page one click from its tab. The old "Guides" grouping is gone. It bundled three things with different audiences and lifetimes, and its name invited exactly the confusion of having both "Guides" and "User guide" in the same tree. The H. polymorpha protocol and the legacy tutorials are now appendices at the end of the user guide, labelled MATLAB-only, where they read as the older material they are. Installation moves to the top of the same section: it is step zero of the guide, the home page already carries the install commands, and no URL changes. The guide overview absorbs the routing that the old Guides landing did, and states plainly that the executed-examples guarantee covers the numbered pages only -- not the protocol or the tutorials. Also fixes the MATLAB snippet on the home page, which printed -sol.f and so reported a growth rate of -0.0809 where the Python tab beside it reported 0.0809. Same negated-objective mistake that was corrected across the guide; index.md is not executed by the harness, so nothing caught it. Measured 0.0809 in both toolboxes.
The section is the evidence behind the defaults -- calibration studies and per-function benchmark notes -- rather than a place to go and tune parameters, which is what the old name suggested to anyone scanning the tabs. Renamed in the nav, the section's own heading, and the two pages that referred to it by name. The URL stays parameter-tuning/, so nothing linked or indexed breaks.
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
1 participant
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.
Reorders the navigation so the two things people actually use are first.
Before / after
navigation.tabsis on, so these are the header tabs. The user guide was fifthand the API sixth, behind a 21-page section of calibration studies that
exists to justify defaults rather than to be read. Guide pages also sat three
levels deep —
Guides > User guide > 4. Simulating growth with FBA.Now the guide is tab 2, the API tab 3, and every guide page is one click from its
tab. Six tabs instead of seven.
"Guides" is gone, and the protocol and tutorials moved into the user guide
Having both Guides and User guide in one tree invited exactly the
confusion it sounds like. The H. polymorpha protocol and the legacy tutorials
are now appendices at the end of the user guide, after page 19, labelled
MATLAB-only.
One distinction is preserved deliberately: the numbered pages are dual-language
and executed on every commit; the protocol and tutorials are neither. The guide
overview now says so explicitly rather than letting the guarantee appear to cover
everything under the tab.
Installation moves to the top of the same section — it is step zero of the guide,
and the home page hero already carries
pip install raven-toolboxand the MATLABAdd-Ons path with a copy button.
No URLs change. This is nav placement only, so nothing linked or indexed
breaks, including the installation pages.
Home page
The cards led with Installation and a "Guides" card pointing at the protocol.
They now lead with User guide and API reference, then Installation and
MATLAB vs Python.
One bug fixed on the way
The MATLAB tab of the home page's first code sample printed
-sol.f:That is the negated-objective mistake corrected across the guide in #28, left
behind on the landing page because
index.mdis not executed by the harness. Itreported a negative growth rate next to a Python tab reporting
0.0809.Measured in both toolboxes on yeast-GEM:
sol.f = 0.0809, matchingobjective_valueexactly.Parameter tuning renamed to Methods & benchmarks
The section holds the evidence behind the defaults — calibration studies and
per-function benchmark notes — rather than a place to go and tune parameters,
which is what the old name suggested to anyone scanning the tabs. Renamed in the
nav, in the section's own heading, and in the two pages that referred to it by
name. The URL stays
parameter-tuning/, so nothing linked or indexed breaks.Final tabs:
Note for the in-flight branch
Based on
main.docs/reconcile-toolbox-studiesadds a nav line for the ftINITstudy, so it will conflict on
mkdocs.yml— the wholenav:block is rewrittenhere. Resolve by re-adding that one study line under Parameter tuning.