Track RAVEN develop3 and render NumPy-style API docs#2
Merged
Conversation
RAVEN's function help is being reformatted to NumPy-style docstrings, which mkdocstrings-matlab renders as structured argument/return tables. Set the matlab handler's docstring_style to numpy so the help is parsed accordingly.
RAVEN's develop3 branch reorganises the toolbox into modular directories (reconstruction, manipulation, analysis, gapfilling, ...) that mirror raven-python's package layout, so the two line up by category. - .gitmodules: track the RAVEN submodule on develop3. - gen_api_pages.py: organise the API reference by develop3's modular categories. - mkdocs.yml: point the MATLAB mkdocstrings handler at the modular directories. The NumPy-style function help that renders these as argument/return tables lands in develop3 via SysBioChalmers/RAVEN#616; once merged, updating the submodule (it now tracks develop3) brings the reformatted docstrings in.
edkerk
changed the title
Track develop3 (RAVEN) and develop (raven-python) in .gitmodules and add a scheduled workflow that bumps the submodule pointers to the tip of their tracked branches once a day, with manual workflow_dispatch support.
edkerk
force-pushed
the
fix/matlab-docstring-style
branch
from
a2f4cd4 to
5c21e10
Compare
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.
Switches the docs site to track RAVEN's develop3 branch and renders the
MATLAB API as structured tables.
Changes
.gitmodulesnow tracks the RAVEN submodule ondevelop3, whose modular layout (reconstruction,manipulation,analysis,gapfilling, …) mirrors raven-python's package structure, so thetwo implementations line up by category in the API reference.
scripts/gen_api_pages.py) — organises the API reference bydevelop3's modular categories.
mkdocstringshandler at the modulardirectories and sets
docstring_style: numpyso NumPy-style help renders asargument/return tables.
Activation
The NumPy-style function help that produces the tables lands in
develop3viaSysBioChalmers/RAVEN#616.
Once that merges,
git submodule update --remote RAVEN(the submodule nowtracks
develop3) pulls the reformatted docstrings and the tables appear.Verified locally against the #616 branch: 18 modular API pages, NumPy docstrings
render as tables,
mkdocs build --strictpasses with no warnings.Automated submodule updates
develop(hanpo-GEMstays onmain)..github/workflows/update-submodules.yml: a scheduled GitHub Action thatruns daily at 04:00 UTC (plus a manual Run workflow button via
workflow_dispatch). It pulls each submodule to the tip of its tracked branchand commits the pointer bump only when something changed. Uses the default
GITHUB_TOKEN(no secrets); the resulting push tomaintriggers the Read theDocs rebuild automatically.
mainpinsto the dev-branch tips — this is intended.