doc: family taxonomy + concepts page + FAQ for end-user docs - #761
Open
tfcollins wants to merge 28 commits into
Open
doc: family taxonomy + concepts page + FAQ for end-user docs#761tfcollins wants to merge 28 commits into
tfcollins wants to merge 28 commits into
Conversation
Reorganizes the supported-devices section so users land on a family landing page instead of a flat 130-row toctree. Each family stub contains a per-part toctree so all existing autodoc pages remain reachable; family overview content is filled in by later commits. Signed-off-by: Travis Collins <travis.collins@analog.com>
Adds a structural assertion so the per-part regenerator cannot silently start managing families/ or the supported-devices index. Signed-off-by: Travis Collins <travis.collins@analog.com>
The supported-devices landing page is now hand-authored (family taxonomy from Task 1 of the doc-improvements plan). The earlier guard assertion was structural only; this commit removes the actual write path that was overwriting it. The script still removes excluded-class per-part rst files and cleans up the temporary adi.rst that sphinx-apidoc produces. Signed-off-by: Travis Collins <travis.collins@analog.com>
Every adi.*.rst under doc/source/devices/ must be referenced from a family file under doc/source/devices/families/. New parts that land without a family assignment now fail CI in the same way that missing emulation contexts do. Signed-off-by: Travis Collins <travis.collins@analog.com>
Two correctness fixes to the new invoke checkdocs gate: - Replace str.removesuffix (Py3.9+) with os.path.splitext so the gate works on the declared Python floor (3.8 per pyproject.toml). - Match toctree lines via a re.M-anchored regex instead of a bare substring check, so a prefix-overlap like '../adi.tdd' inside '../adi.tddn' can't satisfy coverage for both names. Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
CheckParts already installs invoke and groups the sibling checkparts/checkemulation gates. checkdocs is the third member of that family (per tasks.py:381 precommit decorator). Moving it removes a duplicate pip install invoke and lets the gate fail independently of the CheckDocs Sphinx build. Signed-off-by: Travis Collins <travis.collins@analog.com>
Task-oriented symptom -> cause -> fix entries covering the libiio-not-found, no-device-found, empty-rx, cyclic-tx-rearm, stale-property, attr-not-defined, multi-chip-discovery, libiio-v0/v1, and jesd-extras pitfalls. Designed to grow over time as users report issues. Signed-off-by: Travis Collins <travis.collins@analog.com>
New top-level concepts.rst explains the rx/tx/attribute/URI mental model so users have somewhere to land between the quick start and the per-device API reference. Existing pages link into it where they previously assumed prior knowledge. Signed-off-by: Travis Collins <travis.collins@analog.com>
- Complex parts return complex128 (NumPy promotion from int16 I/Q), not complex64. The page now says so explicitly. - The cyclic-buffer rearm path raises a clean exception; the page no longer says 'hangs or errors'. Signed-off-by: Travis Collins <travis.collins@analog.com>
Drops Python 3.6.8 / libiio 0.18 / pyadi 0.0.5 examples in favor of current versions, removes the dated long-form virtualenv walkthrough, and points readers at the concepts page, supported-devices landing, and troubleshooting from the bottom of the page. Signed-off-by: Travis Collins <travis.collins@analog.com>
Replaces the flat list of 5-line snippets with four narrated workflows (capture+plot, cyclic TX, multi-channel capture, annotated IMU output) that show how the pieces fit together. Cross-links to concepts and buffers pages instead of re-explaining mechanics. Signed-off-by: Travis Collins <travis.collins@analog.com>
- Capture example comment now says complex128 to match what NumPy's int16 -> complex promotion actually produces. - Drop the redundant .astype(np.complex64) from the cyclic TX example; tx() extracts I/Q from any complex dtype. Signed-off-by: Travis Collins <travis.collins@analog.com>
- gain_control_mode does not exist on Pluto; use the per-channel gain_control_mode_chan0 (the canonical example at examples/pluto.py uses this form). - ADIS16495 channel order is [anglvel_xyz, accel_xyz, temp], so [0, 3] is anglvel_x + accel_x. The example previously had the comment and dict-key claims inverted; flip rx_enabled_channels to [3, 0] so it matches the prose. - Use double backticks for inline literal in the see-also line. - Point the examples/ link at tree/main instead of tree/master. Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
NumPy promotes int16 I/Q to complex128, not complex64. The family page was inconsistent with concepts.rst; aligning. Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Signed-off-by: Travis Collins <travis.collins@analog.com>
Closes out Phase 4 of the doc-improvements branch. Signed-off-by: Travis Collins <travis.collins@analog.com>
The _mc constructor takes phy_dev_name (singular string), not phy_dev_names (plural list). Signed-off-by: Travis Collins <travis.collins@analog.com>
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.
Summary
End-user documentation refresh on top of the existing Sphinx +
adi_doctoolsbuild.doc/source/devices/families/(RF Transceivers, JESD ADCs, JESD DACs, Precision ADCs, Precision DACs, IMUs, Clocks/PLLs, RF Front-End, Beamformers, Sensors & Specialty, Eval Systems, Utility).doc/source/devices/index.rstbecomes a 12-row family landing page. Per-partadi.<part>.rstfiles stay flat on disk sodoc/update_devs.pykeeps working.doc/source/concepts.rst) explains the rx/tx/attribute/URI mental model — bridges quick-start to per-part API reference. Cross-linked fromattr/,buffers/,connectivity.quick.rstmodernized (Python 3.10, libiio v1.x,make dev),examples.rstexpanded with four end-to-end workflows, newtroubleshooting.rstwith 10 seed FAQ entries.invoke checkdocsgate (tasks.py) asserts every per-partadi.*.rstis referenced from at least one family file. Wired intoprecommitand theCheckPartsCI job.update_devs.pynow skips overwriting the hand-authoreddevices/index.rst.Test plan
make html SPHINXOPTS="-W"passes with zero warningsinvoke checkdocsreports "All 145 per-part doc pages are assigned to a family"make linkcheckpassesCheckPartsjob runsinvoke checkdocsas expected