SPaC-Kit Docs

docs/index.rst

@@ -18,7 +18,9 @@ CCSDSPy
     :alt: Zenodo DOI
 
 CCSDSPy provides an IO Interface for reading CCSDS_ data in Python.
-The CCSDS format is used for many NASA and ESA missions for low-level telemetry, and often contains tightly packed bits to reduce downlink requirements. The library is developed with requirements sourced from the community and extensive automated testing. 
+The CCSDS format is used for many NASA and ESA missions for low-level telemetry, and often contains tightly packed bits to reduce downlink requirements. The library is developed with requirements sourced from the community and extensive automated testing.
+
+**SPaC-Kit** is a companion toolkit built on CCSDSPy that provides command-line tools and workflows for parsing CCSDS files to Excel, generating test packets, and working with mission-specific packet definitions through a plugin system. See :ref:`spac-kit` for details.
 
 .. _CCSDS: https://public.ccsds.org/default.aspx
 
@@ -27,6 +29,7 @@ The CCSDS format is used for many NASA and ESA missions for low-level telemetry,
 
    whatsnew/index
    user-guide/index
+   spac-kit/index
    dev-guide/index
    api
 

docs/spac-kit/autodocs.rst

@@ -0,0 +1,220 @@
+.. _spac-kit-autodocs:
+
+**************************
+Documentation Generation
+**************************
+
+SPaC-Kit includes a **Sphinx extension** that automatically generates comprehensive documentation for CCSDS packet definitions. This is the standout feature of SPaC-Kit, enabling missions to maintain living documentation that stays synchronized with packet definitions.
+
+Overview
+========
+
+The ``spac_kit.autodocs`` Sphinx extension:
+
+- **Discovers** all packet definitions from installed plugins
+- **Generates** RST stub files automatically
+- **Creates** formatted documentation with field tables
+- **Links** field names to detailed descriptions
+- **Styles** output with mission-specific CSS
+
+This eliminates manual documentation maintenance and ensures packet specs stay current with code.
+
+Quick Start
+===========
+
+Add to your Sphinx ``conf.py``:
+
+.. code-block:: python
+
+   extensions = [
+       'sphinx.ext.autodoc',
+       'spac_kit.autodocs',  # Add this line
+   ]
+
+   # Configure which modules to document
+   spacdocs_packet_modules = [
+       'ccsds.packets.europa_clipper.ecm',
+       'ccsds.packets.europa_clipper.status',
+   ]
+
+Then build your docs:
+
+.. code-block:: bash
+
+   sphinx-build -b html docs/ docs/_build/html
+
+The Sphinx Extension
+====================
+
+The extension provides the ``.. spacdocs::`` directive for documenting individual packets, and automatically generates a complete packet index.
+
+Configuration
+=============
+
+In your ``conf.py``:
+
+.. code-block:: python
+
+   extensions = ['spac_kit.autodocs']
+
+   # Required: List of Python module paths containing packet definitions
+   spacdocs_packet_modules = [
+       'ccsds.packets.your_mission.telemetry',
+       'ccsds.packets.your_mission.commands',
+   ]
+
+The extension will:
+
+1. Scan each module for ``_BasePacket`` instances
+2. Generate an RST stub file for each packet
+3. Create a master index file (``_packet_index.rst``)
+4. Copy styling resources to your ``_static`` directory
+
+Using the spacdocs Directive
+=============================
+
+Manual usage (the extension does this automatically):
+
+.. code-block:: rst
+
+   Sensor Data Packet
+   ==================
+
+   .. spacdocs:: ccsds.packets.europa_clipper.ecm.sensor_data
+
+This generates:
+
+- **Summary table** with all fields, types, bit lengths, and offsets
+- **Detail sections** for each field with full attribute listings
+- **Interactive tooltips** showing field descriptions
+- **Hyperlinks** from summary to details
+
+Generated Documentation Structure
+==================================
+
+For each packet, the extension creates:
+
+**Summary Section**
+
+A table showing:
+
+- Field names (clickable, with tooltip descriptions)
+- Data types (with array notation if applicable)
+- Bit lengths
+- Bit offsets (calculated automatically)
+- Byte order
+
+**Detail Sections**
+
+For each field:
+
+- Field name as section header
+- Full description
+- Complete attribute table (data type, bit length, offset, byte order, array shape, array order)
+
+
+Advanced Features
+=================
+
+Field Descriptions
+------------------
+
+Add descriptions to your packet fields:
+
+.. code-block:: python
+
+   PacketField(
+       name='status',
+       data_type='uint',
+       bit_length=8,
+       description='System status flags: bit 0=power, bit 1=thermal'
+   )
+
+Descriptions appear as tooltips in the summary table and as paragraph text in detail sections.
+
+Array Fields
+------------
+
+Array fields are automatically formatted:
+
+.. code-block:: python
+
+   PacketArray(
+       name='sensor_grid',
+       data_type='uint',
+       bit_length=16,
+       array_shape=(32, 32)
+   )
+
+Appears in documentation as: ``uint[32,32]``
+
+Directory Structure
+===================
+
+After building, your docs directory contains:
+
+.. code-block:: text
+
+   docs/
+   ├── conf.py
+   ├── index.rst
+   ├── _static/
+   │   ├── spac-kit.css          # Auto-copied
+   │   └── circle-info.svg       # Auto-copied
+   ├── _autopackets/             # Auto-generated
+   │   ├── packet_name1.rst
+   │   ├── packet_name2.rst
+   │   └── ...
+   └── _packet_index.rst         # Auto-generated
+
+Include ``_packet_index.rst`` in your main toctree:
+
+.. code-block:: rst
+
+   .. toctree::
+      :maxdepth: 2
+
+      introduction
+      _packet_index
+      api
+
+Integration Example
+===================
+
+Complete ``conf.py`` example:
+
+.. code-block:: python
+
+   # Sphinx configuration
+
+   project = 'Europa Clipper Packets'
+   extensions = [
+       'sphinx.ext.autodoc',
+       'sphinx.ext.napoleon',
+       'spac_kit.autodocs',
+   ]
+
+   # SPaC-Kit configuration
+   spacdocs_packet_modules = [
+       'ccsds.packets.europa_clipper.ecm',
+       'ccsds.packets.europa_clipper.ice',
+       'ccsds.packets.europa_clipper.mimi',
+   ]
+
+   # HTML output options
+   html_theme = 'sphinx_rtd_theme'
+   html_static_path = ['_static']
+
+Main documentation file (``index.rst``):
+
+.. code-block:: rst
+
+   Europa Clipper Packet Documentation
+   ====================================
+
+   .. toctree::
+      :maxdepth: 2
+
+      overview
+      _packet_index
+      usage

docs/spac-kit/generator.rst

@@ -0,0 +1,142 @@
+.. _spac-kit-generator:
+
+*******************
+Generating Packets
+*******************
+
+The ``spac-generate`` command creates valid CCSDS packets for testing parsers, data pipelines, and ground software.
+
+Basic Usage
+===========
+
+**Generate all packets:**
+
+.. code-block:: bash
+
+   spac-generate --output test.bin
+
+**Generate specific APIDs:**
+
+.. code-block:: bash
+
+   spac-generate --output test.bin --apid 100 200
+
+**Generate by module:**
+
+.. code-block:: bash
+
+   spac-generate --output test.bin --module europa_clipper.ecm
+
+Command-Line Options
+====================
+
+**Required:**
+
+``-o FILE, --output FILE``
+   Output file path
+
+**Optional:**
+
+``-a APID [APID ...], --apid APID [APID ...]``
+   Generate specific APID(s) only
+
+``-m MODULE [MODULE ...], --module MODULE [MODULE ...]``
+   Generate specific module(s). Can specify full module path (``europa_clipper.ecm``) or specific packet (``europa_clipper.ecm.fg1_low``). The ``ccsds.packets`` prefix is optional.
+
+``-n COUNT, --count COUNT``
+   Number of packets per definition (default: 1)
+
+``-z, --zeros``
+   Generate zero-initialized data instead of random
+
+Examples
+========
+
+**Multiple packets with zeros:**
+
+.. code-block:: bash
+
+   spac-generate --output test.bin --apid 100 200 --count 10 --zeros
+
+**Specific packet by module:**
+
+.. code-block:: bash
+
+   spac-generate --output test.bin --module europa_clipper.ecm.fg1_low
+
+**List available packets:**
+
+.. code-block:: bash
+
+   spac-ls
+
+Output Statistics
+=================
+
+The generator provides file statistics:
+
+.. code-block:: text
+
+   Generating packets to: test.bin
+     Generated 1 packet(s) for APID 100 (SensorPacket)
+
+   Success! Generated packets written to test.bin
+     2,048 bytes, entropy: 7.98 bits/byte (99.8%), chi-squared: p=0.54 (uniform)
+
+- **Entropy**: 0.0 (all same byte) to 8.0 (perfectly random)
+- **Chi-squared p-value**: > 0.05 suggests uniform distribution
+
+Python API
+==========
+
+**Basic generation:**
+
+.. code-block:: python
+
+   import ccsdspy
+   from spac_kit.generator import PacketGenerator
+
+   # Define packet structure
+   fields = [
+       ccsdspy.PacketField(name="status", data_type="uint", bit_length=8),
+       ccsdspy.PacketField(name="temperature", data_type="float", bit_length=32),
+   ]
+   packet_def = ccsdspy.VariableLength(fields, apid=100, name="SensorPacket")
+
+   # Generate packets
+   generator = PacketGenerator(packet_def)
+   with open("packets.bin", "wb") as f:
+       generator.write_packet(f, count=5, use_random=True)
+
+**Generate with plugin packets:**
+
+.. code-block:: python
+
+   from spac_kit.generator import PacketGenerator
+   from spac_kit.parser.util import import_ccsds_packet_packages
+
+   # Load all packet definitions from plugins
+   packets = import_ccsds_packet_packages()
+
+   # Generate for specific APID
+   packet_info = next(p for p in packets if p["packet"].apid == 100)
+   generator = PacketGenerator(packet_info["packet"])
+
+   with open("output.bin", "wb") as f:
+       generator.write_packet(f, count=10, use_random=False)  # zeros
+
+**Test fixture example:**
+
+.. code-block:: python
+
+   import pytest
+   from io import BytesIO
+   from spac_kit.generator import PacketGenerator
+
+   @pytest.fixture
+   def test_packet_data():
+       """Generate test CCSDS packets."""
+       buf = BytesIO()
+       generator = PacketGenerator(my_packet_def)
+       generator.write_packet(buf, count=5, use_random=False)
+       return buf.getvalue()