| name | scopy-doc-format |
| description | RST documentation conventions for Scopy plugins including heading styles, toctree syntax, image placeholders, and attribute table format. Auto-loads when writing RST documentation for Scopy plugins. |
Scopy RST Documentation Conventions
Heading Hierarchy
Top-level title (80 = characters)
================================================================================
Section heading (dashes)
---------------------------------
Subsection heading (tildes)
~~~~~~~~~~~~~~~~~~
The underline must be at least as long as the heading text.
Cross-Reference Labels
.. _<plugin>: # Main doc file
.. _<plugin>_index: # Index file
.. _<plugin>_advanced: # Advanced doc file
Labels must be unique across the entire documentation tree.
Toctree Syntax
.. toctree::
:maxdepth: 2
<plugin>
<plugin>_advanced
- No
.rst extension in toctree entries
- Entries must match actual file names exactly
Image Placeholder Format
Do NOT use .. figure:: or .. image:: directives. Use this comment format:
.. AN_IMAGE_WILL_BE_HERE
Screenshot: <exact description of what to capture>
e.g. "The RX Chain section showing hardware gain and sampling rate controls"
Place one placeholder:
- At the top of the main RST file (full plugin view)
- Per major section (zoomed in on that panel)
- For the advanced tab (if it exists)
Attribute Documentation Format
- **Attribute Name:** One sentence description of what this attribute controls.
- **Another Attribute:** Description without wiki links.
- Use bullet list with bold name followed by colon
- Descriptions are self-contained — no wiki links
- 2-space indentation for RST lists (no tabs)
Index File Structure
.. _<plugin>_index:
<Device Name>
========================================
Overview
--------
<One paragraph about the plugin.>
Features
--------
- **Feature 1:** Description
Supported Devices
-------------------
- **<Device Family>** (list variants)
Getting Started
---------------
**Prerequisites**
- Hardware requirement
- Scopy version X.Y or later
.. toctree::
:maxdepth: 2
<plugin>
<plugin>_advanced
Top-Level Toctree Update
When adding a new plugin, update scopy/docs/plugins/index.rst:
- Add to the bullet list in the appropriate category
- Add to the toctree block at the bottom
- Insert in alphabetical order within the group
