doc: adopt pyadi-iio (cosmic/adi-doctools) Sphinx theme + targeting fixes#204
Merged
Conversation
Replace the furo theme with the cosmic theme provided by adi-doctools, matching pyadi-iio and the rest of the ADI doc fleet. - requirements_doc.txt: drop furo/sphinx-favicon, add adi-doctools tarball, bump sphinx>=5.0 - conf.py: html_theme=cosmic, add adi_doctools extension and needs_extensions floor, set html_favicon directly, trim theme options to light/dark logos, drop furo-only DEV_BUILD announcement - style.css: drop furo sidebar/data-theme rules, keep index-logo background fix - index.md: use cosmic .only-light/.only-dark image classes for the index-page logo
The sphinx_design 'dropdown' directive used for property entries was not styled by the cosmic theme. Switch to adi_doctools' native 'collapsible' directive, which the theme styles via collapsible.scss (.collapsible / .collapsible_input / .collapsible_content), and set hide_collapsible_content=True so properties start collapsed. dropdown was the only sphinx_design feature in use, so drop sphinx_design from extensions and requirements -- this also removes the grid/card/tab-set /tab-item 'already registered' build warnings.
The reference-design diagram used a raw <img src="/_static/..."> with an
absolute path, which 404s once the docs are published under /master/ on
GitHub Pages. Switch it to a {figure} directive so Sphinx resolves and
copies the image (into _images/) like the other pages do, and add a caption.
Also complete the truncated intro sentence and flesh out the empty
Getting Started section with a Prerequisites list and a step-by-step
targeting walkthrough (tool path setup, opening a model, selecting a
reference design in the HDL Workflow Advisor, and running the workflow via
hdlcoder.runWorkflow), cross-linking Installation and the HDL Workflow page.
Collaborator
Author
|
@copilot resolve the merge conflicts in this pull request |
Co-authored-by: tfcollins <854904+tfcollins@users.noreply.github.com>
Contributor
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.
Summary
Switches the Transceiver Toolbox docs to the same Sphinx theme as pyadi-iio (the
cosmictheme fromadi-doctools), and cleans up a couple of doc issues along the way.Changes
requirements_doc.txt: dropfuro/sphinx-favicon, installadi-doctoolsfrom its release tarball, bumpsphinx>=5.0.conf.py:html_theme = "cosmic", addadi_doctoolsextension +needs_extensionsfloor, sethtml_favicondirectly, trim theme options to light/dark logos, drop the furo-onlyDEV_BUILDannouncement banner.style.css: drop furo-specific sidebar/data-themerules; keep the index-logo background fix.index.md: use cosmic's native.only-light/.only-darkclasses for the index-page logo.sysobj.htmltemplate fromsphinx_design'sdropdownto adi_doctools' nativecollapsibledirective (styled by the theme), sethide_collapsible_content = True, and dropsphinx_designentirely (it was only used fordropdown; this also removes the grid/card/tab-set/tab-item "already registered" build warnings).targeting.md): fix the missing reference-design image (was a raw<img src="/_static/...">absolute path that 404s under/master/; converted to a{figure}directive so Sphinx resolves/copies it), complete a truncated intro sentence, and flesh out the empty Getting Started section with prerequisites and a step-by-step targeting walkthrough.Verification
Built locally with the cosmic theme on each change:
app.min.css/app.umd.js), favicon, and light/dark header + index logos all wire up..collapsible*markup, collapsed by default; no sphinx_design conflict warnings remain._images/with a depth-correctsrc; the new sections and cross-page links render with notargeting.mdwarnings.Remaining build warnings in a local build are only the MATLAB-generated System Object / reference-design pages, which are produced by
gen_sysobj_docin CI.