docs: improve getting_started and installation readability

- Consolidate installation steps into installation.rst (pip upgrade,
  ria --help verification, entrypoints note, editable install note,
  SDR driver table); replace getting_started §1 body with a link
- Reformat command and subcommand lists as tables with purpose
  descriptions and internal ref links for navigation
- Remove redundant §6 tips and §9 cheat sheet; trim duplicate
  descriptions in generate subcommand sections
- Fix inline code comments to sit beside the command they describe
- Add custom CSS for light body text, white headings, and table
  header colour to suit the dark background theme

docs/source/_static/custom.css

@@ -1,6 +1,7 @@
 /* Change the hex values below to customize heading colours */
 
-.rst-content h1 { color: #2c3e50; }
+.rst-content { color: #e0e0e0; }
+.rst-content h1 { color: #ffffff; }
 .rst-content h2,
 .rst-content h2 a { color: #ffffff !important; font-size: 22px !important; }
 
@@ -22,8 +23,20 @@
 .rst-content .admonition.warning p {
     color: #ffffff !important;
 }
-.rst-content h4 { color: #404040; }
+.rst-content h4 { color: #cccccc; }
 
 .highlight * { color: #ffffff !important; }
 
 .ria-cmd { color: #2980b9 !important; }
+
+
+/* Table header text */
+.rst-content table.docutils th {
+    color: #ffffff !important;
+}
+
+/* Remove alternating row background colors from tables */
+.rst-content table.docutils td,
+.rst-content table.docutils tr:nth-child(2n-1) td {
+    background-color: transparent !important;
+}

docs/source/intro/getting_started.rst

@@ -6,10 +6,10 @@ This is a practical reference for the ``ria`` CLI from ``ria-toolkit-oss``.
 
 **Scope of this guide:**
 
-* Installation and setup
+* **Installation and SDR driver prerequisites** — how to install RIA Toolkit OSS and configure the system drivers your hardware requires
-* End-to-end CLI workflows
+* **End-to-end CLI workflow** — a step-by-step walkthrough from hardware discovery through capture, annotation, and processing
-* Full command reference for CLI features
+* **Full command reference** — options, flags, and examples for every ``ria`` command
-* Brief scripting section
+* **Python scripting preview** — using the toolkit API directly without the CLI
 
 **Official resources:**
 
@@ -18,76 +18,15 @@ This is a practical reference for the ``ria`` CLI from ``ria-toolkit-oss``.
 * `PyPI package <https://pypi.org/project/ria-toolkit-oss/>`_
 * `RIA Hub Conda package <https://riahub.ai/qoherent/-/packages/conda/ria-toolkit-oss>`_
 
-.. contents:: Contents
-   :local:
-   :depth: 2
-   :backlinks: none
-
 
 1) Installation and Setup
 ==========================
 
-1.1 Installation with Conda
+Before using the ``ria`` CLI, follow the :doc:`Installation <installation>` guide to
-----------------------------
+install RIA Toolkit OSS and any SDR drivers required for your hardware.
-
-RIA Toolkit OSS is available as a Conda package on RIA Hub. This is typically the easiest
-path when using SDR tooling that depends on native/system libraries.
-
-.. code-block:: bash
-
-   conda update --force conda
-   conda config --add channels https://riahub.ai/api/packages/qoherent/conda
-   conda activate base
-   conda install ria-toolkit-oss
-
-Verify:
-
-.. code-block:: bash
-
-   conda list | grep ria-toolkit-oss
 
 
-1.2 Installation with pip
+1.1 SDR driver prerequisites
---------------------------
-
-Use pip unless you specifically need to edit toolkit source.
-
-.. code-block:: bash
-
-   python3 -m venv .venv
-   source .venv/bin/activate
-   pip install --upgrade pip
-   pip install ria-toolkit-oss
-
-Verify CLI entrypoint:
-
-.. code-block:: bash
-
-   ria --help
-
-``pyproject.toml`` defines two script entry points:
-
-* ``ria``
-* ``ria-tools``
-
-Both point to the same CLI module (``ria_toolkit_oss_cli.cli:cli``).
-
-
-1.3 Optional install from source
-----------------------------------
-
-Use this for local development or testing unreleased changes.
-
-.. code-block:: bash
-
-   git clone https://riahub.ai/qoherent/ria-toolkit-oss.git
-   cd ria-toolkit-oss
-   python3 -m venv .venv
-   source .venv/bin/activate
-   pip install -e .
-
-
-1.4 SDR driver prerequisites
 -----------------------------
 
 Toolkit package install does not install all system SDR drivers. Install vendor/runtime
@@ -95,11 +34,22 @@ dependencies for the hardware you use.
 
 Examples (depends on device and OS):
 
-* USRP: UHD drivers
+.. list-table::
-* Pluto: libiio / IIO utilities
+   :widths: 25 75
-* BladeRF: libbladeRF
+   :header-rows: 1
-* HackRF: libhackrf
+
-* RTL-SDR: librtlsdr
+   * - Device
+     - Driver Package
+   * - USRP
+     - UHD drivers
+   * - Pluto
+     - libiio / IIO utilities
+   * - BladeRF
+     - libbladeRF
+   * - HackRF
+     - libhackrf
+   * - RTL-SDR
+     - librtlsdr
 
 See repo docs under ``docs/source/sdr_guides/*`` and your OS package instructions.
 
@@ -119,18 +69,34 @@ Top-level CLI follows this model:
 
 **Top-level commands:**
 
-* ``discover``
+.. list-table::
-* ``init``
+   :widths: 25 75
-* ``capture``
+   :header-rows: 1
-* ``view``
+
-* ``annotate`` (group)
+   * - Command
-* ``convert``
+     - Purpose
-* ``split``
+   * - :ref:`discover <cmd-discover>`
-* ``combine``
+     - Probe SDR drivers and enumerate attached hardware
-* ``generate`` (group)
+   * - :ref:`init <cmd-init>`
-* ``transform`` (group)
+     - Create and manage user metadata defaults
-* ``transmit``
+   * - :ref:`capture <cmd-capture>`
-* ``synth`` (alias of ``generate`` in command bindings)
+     - Record IQ samples from a connected SDR
+   * - :ref:`view <cmd-view>`
+     - Generate visualizations from IQ files
+   * - :ref:`annotate <cmd-annotate>`
+     - Label signal regions manually or with auto-detection (group)
+   * - :ref:`convert <cmd-convert>`
+     - Convert between IQ file formats
+   * - :ref:`split <cmd-split>`
+     - Split, trim, or extract recordings
+   * - :ref:`combine <cmd-combine>`
+     - Merge multiple recordings by concatenation or addition
+   * - :ref:`generate / synth <cmd-generate>`
+     - Generate synthetic IQ signals (group; ``synth`` is an alias)
+   * - :ref:`transform <cmd-transform>`
+     - Apply augmentations or impairments to recordings (group)
+   * - :ref:`transmit <cmd-transmit>`
+     - Transmit IQ through a TX-capable SDR
 
 
 3) Quick End-to-End Workflow
@@ -158,10 +124,8 @@ provenance fields.
 .. code-block:: bash
 
    ria init
-   # or non-interactive
+   ria init --author "Jane Doe" --project "rf-campaign-1" --location "Lab-A"  # non-interactive
-   ria init --author "Jane Doe" --project "rf-campaign-1" --location "Lab-A"
+   ria init --show  # show config
-   # show config
-   ria init --show
 
 
 3.3 Capture IQ
@@ -227,13 +191,14 @@ Replay recorded or synthesized IQ through a transmit-capable SDR.
 .. code-block:: bash
 
    ria transmit -d hackrf -f 2.44G -s 2e6 --input capture.sigmf-data
-   # or generated waveform
+   ria transmit -d hackrf --generate lfm --continuous  # generated waveform
-   ria transmit -d hackrf --generate lfm --continuous
 
 
 4) Command Reference
 =====================
 
+.. _cmd-discover:
+
 4.1 ``discover``
 -----------------
 
@@ -263,6 +228,8 @@ Replay recorded or synthesized IQ through a transmit-capable SDR.
   hidden in default output.
 
 
+.. _cmd-init:
+
 4.2 ``init``
 -------------
 
@@ -309,6 +276,8 @@ Replay recorded or synthesized IQ through a transmit-capable SDR.
    generate metadata, and YAML config loading paths).
 
 
+.. _cmd-capture:
+
 4.3 ``capture``
 ----------------
 
@@ -382,6 +351,8 @@ Device selection (``--device``) is optional if only one device is detected. Exac
    ria capture -c capture_config.yaml
 
 
+.. _cmd-view:
+
 4.4 ``view``
 -------------
 
@@ -444,6 +415,8 @@ Device selection (``--device``) is optional if only one device is detected. Exac
    ria view old.npy --legacy --type simple
 
 
+.. _cmd-annotate:
+
 4.5 ``annotate`` group
 -----------------------
 
@@ -459,8 +432,30 @@ Device selection (``--device``) is optional if only one device is detected. Exac
 
    ria annotate <subcommand> ...
 
-**Subcommands:** ``list``, ``add``, ``remove``, ``clear``, ``energy``, ``cusum``,
+**Subcommands:**
-``threshold``, ``separate``
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Subcommand
+     - Purpose
+   * - ``list``
+     - Inspect all annotations on a recording
+   * - ``add``
+     - Add one annotation with explicit sample-domain bounds
+   * - ``remove``
+     - Remove one annotation by index
+   * - ``clear``
+     - Remove all annotations from a recording
+   * - ``energy``
+     - Auto-detect regions above the estimated noise floor
+   * - ``cusum``
+     - Auto-detect regime changes using change-point detection
+   * - ``threshold``
+     - Auto-detect regions using normalized magnitude thresholding
+   * - ``separate``
+     - Decompose annotations into narrower spectral components
 
 **General behavior:**
 
@@ -590,6 +585,8 @@ annotations.
    ria annotate separate capture.sigmf-data --indices 0,1 --verbose
 
 
+.. _cmd-convert:
+
 4.6 ``convert``
 ----------------
 
@@ -629,6 +626,8 @@ inferred from the output file extension.
    ria convert old.npy --format sigmf --legacy --overwrite
 
 
+.. _cmd-split:
+
 4.7 ``split``
 --------------
 
@@ -670,6 +669,8 @@ Choose exactly one operation per invocation:
    ria split annotated.sigmf-data --extract-annotations --annotation-label payload
 
 
+.. _cmd-combine:
+
 4.8 ``combine``
 ----------------
 
@@ -717,6 +718,8 @@ Choose exactly one operation per invocation:
    ria combine signal.npy pattern.npy out.npy --mode add --align-mode repeat-spaced --repeat-spacing 10000
 
 
+.. _cmd-generate:
+
 4.9 ``generate`` group (and ``synth`` alias)
 ---------------------------------------------
 
@@ -728,15 +731,34 @@ Choose exactly one operation per invocation:
 
 ``ria synth ...`` is an alias for ``ria generate ...``.
 
-**Shape:**
+**Usage:**
 
 .. code-block:: bash
 
    ria generate <subcommand> [subcommand options] [common options]
 
 **Available subcommands:**
-``tone``, ``noise``, ``chirp``, ``square``, ``sawtooth``, ``qam``, ``apsk``, ``pam``,
+
-``fsk``, ``ook``, ``oqpsk``, ``gmsk``, ``psk``
+.. list-table::
+   :widths: 30 70
+   :header-rows: 1
+
+   * - Subcommand(s)
+     - Description
+   * - ``tone``
+     - Clean sinusoidal calibration/reference source
+   * - ``noise``
+     - Baseline noise floor data or controlled additive-noise synthesis
+   * - ``chirp``
+     - Sweep-based radar/sonar-style signals and bandwidth occupancy tests
+   * - ``square``, ``sawtooth``
+     - Periodic waveform primitives
+   * - ``qam``, ``apsk``, ``pam``, ``psk``
+     - Digital modulation families with pulse-shaping filter support
+   * - ``fsk``
+     - Frequency-shift keying with configurable tone spacing
+   * - ``ook``, ``oqpsk``, ``gmsk``
+     - On-off keying and continuous-phase modulation schemes
 
 **Common options shared across all generators:**
 
@@ -760,22 +782,16 @@ Multipath and IQ imbalance flags apply impairment-style post-processing during g
 
 Options: ``--frequency``, ``--amplitude``, ``--phase``
 
-Clean sinusoidal calibration/reference source.
-
 ``noise``
 ~~~~~~~~~~
 
 Options: ``--noise-type {gaussian,uniform}``, ``--power``
 
-Baseline noise floor data or controlled additive-noise synthesis.
-
 ``chirp``
 ~~~~~~~~~~
 
 Options: ``--bandwidth`` (required), ``--period`` (required), ``--type {up,down,up_down}``
 
-Sweep-based radar/sonar-style signals and bandwidth occupancy tests.
-
 ``square``
 ~~~~~~~~~~~
 
@@ -826,6 +842,8 @@ symbol transition sharpness).
    ria synth psk -s 2e6 -r 100e3 -M 8 -N 8000 -o psk8.npy
 
 
+.. _cmd-transform:
+
 4.10 ``transform`` group
 -------------------------
 
@@ -834,7 +852,7 @@ symbol transition sharpness).
 * Apply algorithmic transforms to existing recordings.
 * Run reusable augmentations/impairments for dataset diversity and robustness testing.
 
-**Shape:**
+**Usage:**
 
 .. code-block:: bash
 
@@ -895,6 +913,8 @@ inspect parameter hints. ``--view`` writes a PNG preview alongside transform out
    ria transform custom my_filter in.npy out.npy --transform-dir ./my_transforms --params cutoff=0.2
 
 
+.. _cmd-transmit:
+
 4.11 ``transmit``
 ------------------
 
@@ -993,17 +1013,7 @@ experiment-specific fields on the CLI.
    ria generate noise --config generate.yaml
 
 
-6) Practical Tips and Safety
+6) Version Notes
-=============================
-
-* Use ``ria discover`` before capture/transmit sessions.
-* Keep TX gain conservative first; validate with attenuators/dummy loads when needed.
-* Prefer SigMF for interoperable metadata and annotations.
-* For long workflows, keep outputs organized by campaign directories and consistent prefixes.
-* Use ``--verbose`` when debugging device init or driver issues.
-
-
-7) Version Notes
 =================
 
 These notes are based on the current implementation and should be re-validated against future
@@ -1016,11 +1026,12 @@ releases.
 3. Multiple non-CLI modules still import ``utils.*``, which can create runtime dependency
    coupling when using only ``ria-toolkit-oss`` in isolation.
 
-If you observe unexpected import errors after install, check the package version and
+.. tip::
-changelog, then test ``ria --help`` in a clean virtual environment.
+   If you observe unexpected import errors after install, check the package version and
+   changelog, then test ``ria --help`` in a clean virtual environment.
 
 
-8) Brief Scripting (Python) Preview
+7) Brief Scripting (Python) Preview
 =====================================
 
 For quick non-CLI use:
@@ -1037,47 +1048,3 @@ For quick non-CLI use:
    to_sigmf(imp, filename="capture_awgn", path=".")
 
 You can also call annotation algorithms and block-generator primitives from Python directly.
-
-
-9) Cheat Sheet
-===============
-
-.. code-block:: bash
-
-   # Install
-   pip install ria-toolkit-oss
-
-   # Discover
-   ria discover -v
-
-   # Init defaults
-   ria init --author "Jane" --project "rf1" --location "Lab-A"
-
-   # Capture
-   ria capture -d pluto -f 2.44G -s 2e6 -n 1000000 -o cap.sigmf-data
-
-   # View
-   ria view cap.sigmf-data --type simple
-
-   # Annotate
-   ria annotate energy cap.sigmf-data --threshold 1.2
-   ria annotate list cap.sigmf-data --verbose
-
-   # Convert
-   ria convert cap.sigmf-data cap.npy
-
-   # Split
-   ria split cap.sigmf-data --split-every 100000 --output-dir chunks
-
-   # Combine
-   ria combine chunks/a.npy chunks/b.npy merged.npy
-
-   # Generate
-   ria generate qam -s 2e6 -r 100e3 -M 16 -N 5000 -o qam16.npy
-
-   # Transform
-   ria transform augment channel_swap cap.npy
-   ria transform impair add_awgn_to_signal cap.npy --params snr=10
-
-   # Transmit
-   ria transmit -d hackrf --input cap.sigmf-data -f 2.44G -s 2e6

docs/source/intro/installation.rst

@@ -4,7 +4,26 @@ Installation
 RIA Hub Toolkit OSS can be installed either as a Conda package or as a standard Python package.
 
 Please note that SDR drivers must be installed separately. Refer to the relevant guide in the
-:ref:`SDR Guides <sdr_guides>` section of the documentation for addition setup instructions.
+:ref:`SDR Guides <sdr_guides>` section of the documentation for additional setup instructions.
+
+Common driver packages by device (exact package names depend on your OS):
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Device
+     - Driver Package
+   * - USRP
+     - UHD drivers
+   * - Pluto
+     - libiio / IIO utilities
+   * - BladeRF
+     - libbladeRF
+   * - HackRF
+     - libhackrf
+   * - RTL-SDR
+     - librtlsdr
 
 We want your experience with RIA Toolkit OSS to be as smooth and frictionless as possible. If you run into any 
 issues during installation, please reach out to our support team: ``support@qoherent.ai``.
@@ -84,12 +103,22 @@ Please follow the steps below to install RIA Toolkit OSS using pip:
       python -m venv venv
       venv\Scripts\activate
 
-2. Install RIA Toolkit OSS from PyPI with pip:
+2. Upgrade pip and install RIA Toolkit OSS:
 
    .. code-block:: bash
 
+      pip install --upgrade pip
       pip install ria-toolkit-oss
 
+3. Verify the CLI is available:
+
+   .. code-block:: bash
+
+      ria --help
+
+   A successful install prints the top-level help text. ``pyproject.toml`` registers two
+   entrypoints — ``ria`` and ``ria-tools`` — that both point to the same CLI module.
+
 RIA Toolkit OSS can also be installed from RIA Hub. However, RIA Hub does not yet support a proxy or cache for public packages. 
 We intend to add this missing functionality soon. In the meantime, please use the ``--no-deps`` option with pip to skip automatic
 dependency installation, and then manually install each dependency afterward.
@@ -119,3 +148,6 @@ Follow the steps below to install RIA Toolkit OSS from source:
    .. code-block:: bash
 
       pip install .
+
+   For local development, use ``pip install -e .`` instead to install in editable mode
+   so local changes take effect immediately without reinstalling.