Conversation
Build the toolbox documentation with Sphinx and the cosmic theme from adi-doctools, matching pyadi-iio. Pages stay in Markdown and are parsed with MyST. - docs/ becomes the Sphinx source directory; navigation moves from mkdocs.yml to toctrees, and the _pages Jinja indirection is dropped since hiding the theme chrome for MATLAB is now a CSS override - Convert mkdocs-material syntax: admonitions, mermaid fences, numbered code blocks, and raw <img> tags - Replace the hand-rolled collapsible properties on device pages with the theme's collapsible directive - Inline the reference design SVGs so their sub-blocks stay clickable, and restyle them with the theme's CSS variables - Point helptoc.xml at Sphinx's page URLs so MATLAB's help browser keeps working - Stop tracking generated pages and assets, several were stale - Remove the unused sphinx-rtd-theme scaffolding under gen_doc/source Claude-Session: https://claude.ai/code/session_01Bba3uKPPNjK8musGxR8vrf
GitHub runners no longer ship Python 3.9, which failed the job at the setup-python step. Move to 3.11 and update the deprecated action versions.
The errata-ai/Google style repository was renamed to vale-cli/Google, so the releases API now answers with a 301. Without -L curl returned the redirect body instead of the release JSON, no asset was downloaded, and unzip failed.
The lint step pointed at a docs directory that does not exist, so Vale read empty stdin and reported nothing. Point it at the Sphinx sources.
Vale was linting the Jinja templates under docs/_tmpl and the MATLAB live script exports under docs/models, where its findings are noise, so restrict it to the top level pages. The accept list had 'ip usb' on a single line, which matched neither term. Split it and add the technical vocabulary the pages use.
Listing these lowercase made Vale.Terms enforce that casing, flagging 'IP core' and 'USB'. Use case permissive patterns, matching how adc and dac are already handled.
Accept both cases for decimator/interpolator (same pattern used for ip/usb/iio), format MATLAB class paths as inline code so Vale treats them as code rather than prose, and fix ordinal/quote-punctuation/ capitalization style errors in targeting.md and streaming.md. Claude-Session: https://claude.ai/code/session_01TrDkpfceW2nazDddJsEz2F
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.
Builds the toolbox documentation with Sphinx and the
cosmictheme fromadi-doctools, matching
pyadi-iio. Pages stay in
Markdown and are parsed with MyST, so most content carried over unchanged.
Structure
CI/gen_doc/docsis now the Sphinx source directory.mkdocs.ymlto toctrees, with generatedsysobjects/index.mdandhdlrefdesigns/index.mdsection pages._pages/Jinja indirection is dropped. It existed to inject themkdocs
hide: navigationfront matter for the MATLAB build; that is nowa CSS override selected by the
MATLABenv var._templates/is renamed_tmpl/so it does not collide with Sphinx'sown template lookup. Its templates emit MyST instead of mkdocs HTML.
stylesheets/moves to_static/css/, and the unusedsphinx-rtd-themescaffolding undergen_doc/source/is removed.Content
Converted mkdocs-material syntax:
!!! warningadmonitions,```mermaidfences,linenums="1"code blocks, and raw<img>tags.Device interface pages use the theme's
collapsibledirective forproperties, replacing the hand-rolled button/JS/CSS implementation.
The HDL reference design diagrams are inlined with
raw:: htmlratherthan served through
<img>, which would have broken both the clickablesub-blocks and the external stylesheet.
gen_rd_svg.pynow emits thetheme's CSS variables instead of mkdocs-material's.
Generated files
docs/sysobjects/,docs/hdlrefdesigns/,helptoc.xml, the*_custom.svgdiagrams, andrd_style.cssare no longer tracked. Thecommitted copies had drifted — 8 of 17 device pages, 8 of 16 reference
designs, plus an
output1.mdthat no source produces.make docregenerates them before every build.
MATLAB help browser
make doc_mlstill works.MATLAB=ONenables the theme'sstandaloneoption and adds
_static/css/matlab.cssto hide the theme chrome, andhelptoc.xmlnow points at Sphinx's flatpage.htmlURLs rather thanmkdocs'
page/index.html.Notes
make -C CI/gen_doc docbuilds clean from a fresh tree with no Sphinxwarnings. Both
docanddoc_mltargets were verified end to end.adi-doctools0.4.45 from PyPI. CI installs theGitHub
latesttarball as pyadi-iio does, so thedoc.ymlrun on thisPR is the first check against that build.
doc.ymlmoves to Python 3.11 and drops the now unnecessaryapt install python3-numpy.build.ymlstill callsmake docrather thandoc_mlwhen packagingthe toolbox. That is pre-existing behavior and left alone here.