OpenParable
Skip to content
← Back to skills

Scopy Doc Format

Documents
scopy-doc-format

Scopy Doc Format is an Agent Skill for documents published in the analogdevicesinc/scopy repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/analogdevicesinc/scopy/blob/HEAD/tools/scopy_dev_plugin/skills/scopy-doc-format/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/scopy-doc-format, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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