rtd help

CHANGELOG.md

@@ -33,9 +33,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Read the Docs: standard sphinx-rtd-theme palette (dark grey sidebar frame,
   light content panel, default blue links/headings); explicit table/body text
-  contrast on the light panel; browser tab favicon and landing-page logo use the
-  app icon on an opaque white background (``scripts/generate_docs_favicon.py``);
-  screenshots and figures
+  contrast on the light panel; browser tab favicon uses the app icon on an opaque
+  white background (``scripts/generate_docs_favicon.py``); the landing-page logo
+  keeps a transparent background; screenshots and figures
   capped at 65% width (centered) via ``docs/_static/custom.css``.
 - Docs screenshot pipeline: wizard captures use 65% of the app's normal step window
   size (``WIZARD_SCREENSHOT_SIZE_RATIO`` in ``tests/docs/screenshot_helpers.py``)
@@ -47,8 +47,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Read the Docs: note on ``output_format.rst`` and ``longitudinal_report.rst`` that
   session and longitudinal report screenshots and example files are synthetic
   documentation only (not real clinical data).
-- Read the Docs: new ``overview.rst`` (Getting Started) — clinical motivation
-  and design; ``quickstart`` moved to User Guide; workflow-choice table shown
+- Read the Docs: new ``overview.rst`` (Getting Started) — motivation and
+  design; ``quickstart`` moved to User Guide; workflow-choice table shown
   without horizontal scroll.
 
 ### Fixed

docs/_static/custom.css

@@ -69,15 +69,6 @@ section.wy-nav-content-wrap,
   background-color: #f3f6f6;
 }
 
-/* Home / quickstart workflow table — no horizontal scroll wrapper. */
-.wy-nav-content .wy-table-responsive:has(.workflow-choice-table) {
-  overflow: visible;
-}
-
-.wy-nav-content .workflow-choice-table {
-  width: 100%;
-}
-
 /* Breadcrumbs sit on the dark canvas, outside the light panel. */
 .wy-nav-content-wrap .wy-breadcrumbs li,
 .wy-nav-content-wrap .wy-breadcrumbs li a {
@@ -112,11 +103,21 @@ section.wy-nav-content-wrap,
   box-shadow: 0 2px 12px rgba(0, 0, 0, 0.12);
 }
 
+/* Dialog screenshots: intrinsic size (65% cap applies to main window only). */
+.rst-content img.screenshot-dialog,
+.wy-nav-content img.screenshot-dialog {
+  display: block;
+  width: auto !important;
+  max-width: none;
+  height: auto;
+  margin-inline: auto;
+  border-radius: 4px;
+  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.12);
+}
+
 /* Home-page logo keeps its explicit :width: from RST. */
 .rst-content img[src*="logo.png"],
-.rst-content img[src*="logo_docs.png"],
-.wy-nav-content img[src*="logo.png"],
-.wy-nav-content img[src*="logo_docs.png"] {
+.wy-nav-content img[src*="logo.png"] {
   max-width: none;
   box-shadow: none;
 }

docs/index.rst

@@ -3,22 +3,23 @@
 DBS Annotator
 =============
 
-.. image:: _static/logo_docs.png
+.. image:: _static/logo.png
    :alt: DBS Annotator
    :align: center
    :width: 180px
 
-**DBS Annotator** is a desktop application for recording and analysing
-Deep Brain Stimulation (DBS) clinical programming sessions.  It guides
-the clinician or researcher through a DBS programming pipeline: initial
-electrode configuration, clinical scales, and general annotations;
-real-time stimulation adjustments; and session-specific scale changes and
-notes.  Finally, it can generate structured Word and PDF reports from the
-programming session data.
+**DBS Annotator** is a desktop application for recording and analysing Deep Brain
+Stimulation (DBS) clinical programming sessions. It guides the clinician or
+researcher through a DBS programming pipeline: initial electrode configuration,
+clinical scales, and general annotations; real-time stimulation adjustments;
+and session-specific scale changes and notes. Data are saved in timestamped TSV
+files. The application can generate structured Word and PDF reports from one
+session or from several sessions combined.
 
-Developed at the **Brain Modulation Lab, Massachusetts General Hospital**
-(Boston, USA), the **Wyss Center for Bio and Neuroengineering** (Geneva,
-Switzerland), and **Charité Universitätsmedizin Berlin** (Germany).
+**DBS Annotator** was born at the **Brain Modulation Lab, Massachusetts General Hospital**
+(Boston, USA), then transferred to **Charité Universitätsmedizin Berlin** (Berlin, Germany),
+and is from 2026 on maintained at the **Wyss Center for Bio and Neuroengineering** (Geneva,
+Switzerland).
 
 .. note::
 
@@ -73,19 +74,18 @@ Quick Overview
    :header-rows: 0
 
    * - **Complete Workflow**
-     - Record stimulation parameters, clinical scales, and notes
-       step-by-step in a timestamped TSV table.  Export a structured report
-       (Word / PDF) with tables, electrode diagrams, and session-scale
-       timeline charts.
+     - Record stimulation parameters, clinical scales, and notes step by step in
+       a timestamped TSV table. Export a structured report (Word / PDF) with
+       tables, electrode diagrams, and session-scale timeline charts.
    * - **Annotations-only Workflow**
      - Quick timestamped text notes.
    * - **Session and longitudinal reports**
-     - Combine single or multiple session files into a single comparative
-       document with overview tables, clinical and session-scale charts,
-       electrode diagrams, and programming summaries.
+     - Combine single or multiple session files into one comparative document
+       with overview tables, clinical and session-scale charts, electrode
+       diagrams, and programming summaries.
    * - **BIDS-compliant output**
      - Data saved as
        ``sub-XXXX_ses-YYYYMMDD_task-<TASK>_run-XX_<type-of-data>.<ext>``.
    * - **Self-contained desktop app**
-     - Packaged installers (``.msi``, ``.dmg``, ``.deb``); no separate
-       Python runtime required.
+     - Packaged installers (``.msi``, ``.dmg``, ``.deb``); no separate Python
+       runtime required.

docs/installation.rst

@@ -1,26 +1,26 @@
 Installation
 ============
 
-DBS Annotator is a **self-contained desktop application** — no Python or
-extra libraries are required to run the packaged build.  Session data are
-plain ``.tsv`` files in a folder you choose when you start a session.
+DBS Annotator is a **self-contained desktop application**. No Python or extra
+libraries are required to run the packaged build. Session data are plain
+``.tsv`` files in a folder you choose when you start a session.
 
 ----
 
 For end users
 -------------
 
-You can find installation files for **Windows** (``.msi``), **macOS**
-(``.dmg``), and **Linux** (``.deb``) on
+Installation files for **Windows** (``.msi``), **macOS** (``.dmg``), and
+**Linux** (``.deb``) are on
 `GitHub Releases <https://github.com/Brain-Modulation-Lab/DBSAnnotator/releases>`_.
 
-However, the files are **unsigned**, so a warning may appear during
-installation or on first launch.  You must accept the risk and continue.
-On Windows, see :ref:`windows-smartscreen` if SmartScreen blocks the app.
+The files are **unsigned**, so a warning may appear during installation or on
+first launch. You must accept the risk and continue. On Windows, see
+:ref:`windows-smartscreen` if SmartScreen blocks the app.
 
-In some cases — for example when your organization has strict settings — a
-direct download may not be possible.  Use the **install commands below** for
-your operating system.
+In some cases, for example when your organization has strict settings, a direct
+download may not be possible. Use the install commands below for your operating
+system.
 
 ----
 
@@ -29,8 +29,8 @@ your operating system.
 Windows — SmartScreen warnings
 ------------------------------
 
-Release builds are not code-signed.  **Windows Defender SmartScreen** may
-block the installer (``.msi``) or the application on first launch.
+Release builds are not code-signed. **Windows Defender SmartScreen** may block
+the installer (``.msi``) or the application on first launch.
 
 If you see **"Windows protected your PC"** or **"Microsoft Defender SmartScreen
 prevented an unrecognized app from starting"**:
@@ -39,8 +39,8 @@ prevented an unrecognized app from starting"**:
 2. Click **Run anyway** (installer) or **Run** (application).
 
 If your organization blocks unsigned software entirely, use the PowerShell
-install command below (portable build under your user profile), or ask IT for
-an exception.
+install command below (portable build under your user profile), or ask IT for an
+exception.
 
 ----
 
@@ -68,9 +68,9 @@ Start Menu shortcut.
 macOS / Linux — shell install
 -----------------------------
 
-**macOS** and **Linux** use the same install script.  It needs **Python 3**
-and ``curl`` or ``wget``.  On macOS it prefers the release **raw** ``.tar.gz``,
-otherwise the ``.dmg``.  On Linux (x86_64) it prefers the raw ``.tar.gz``,
+**macOS** and **Linux** use the same install script. It needs **Python 3** and
+``curl`` or ``wget``. On macOS it prefers the release **raw** ``.tar.gz``,
+otherwise the ``.dmg``. On Linux (x86_64) it prefers the raw ``.tar.gz``,
 otherwise the published ``.deb``.
 
 .. code-block:: sh
@@ -82,9 +82,9 @@ otherwise the published ``.deb``.
    wget -qO- https://raw.githubusercontent.com/Brain-Modulation-Lab/DBSAnnotator/main/scripts/install.sh | sh
 
 On **macOS**, if you install from the ``.dmg`` manually instead: open the disk
-image from GitHub Releases and drag **DBSAnnotator** to *Applications*.  On
-first launch, right-click → **Open** → **Open** again (required once when the
-app is not notarized).
+image from GitHub Releases and drag **DBSAnnotator** to *Applications*. On first
+launch, right-click → **Open** → **Open** again (required once when the app is
+not notarized).
 
 On **Linux** non-x86_64 systems, install the ``.deb`` from Releases manually or
 build from source (see :doc:`contributing`).
@@ -95,7 +95,7 @@ Updating
 --------
 
 Updating the application does **not** change your session ``*_events.tsv``
-files — they stay in the folders you chose in the app.
+files. They stay in the folders you chose in the app.
 
 Re-run the same install command
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -118,8 +118,8 @@ Automatic update notification
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When enabled, the app checks GitHub Releases (about once per day) and notifies
-you if a newer version is available.  No patient or session data are sent.
-Toggle checks from **Help**, or opt out on the update dialog.  See :doc:`faq`
+you if a newer version is available. No patient or session data are sent.
+Toggle checks from **Help**, or opt out on the update dialog. See :doc:`faq`
 (*How does the automatic update checker work?*).
 
 Installer from GitHub Releases
@@ -134,9 +134,9 @@ and run it over the previous install.
 Data storage
 ------------
 
-The application does not use a database or registry entries for clinical
-data.  All recordings are tab-separated ``.tsv`` files in the output folder
-you select at session start.  Column schema: :doc:`output_format`.
+The application does not use a database or registry entries for clinical data.
+All recordings are tab-separated ``.tsv`` files in the output folder you select
+at session start. Column schema: :doc:`output_format`.
 
 ----
 

docs/longitudinal_report.rst

@@ -1,10 +1,10 @@
 Longitudinal Report
 ===================
 
-The Longitudinal Report workflow combines data from **multiple programming-session
-TSV files** for the **same subject** into a single comparative document.  Use it
-to track a patient's progression across visits.  Files must follow the BIDS
-``task-programming`` naming convention (e.g.
+The Longitudinal Report workflow combines data from **multiple
+programming-session TSV files** for the **same subject** into a single
+comparative document. Use it to track a patient's progression across visits.
+Files must follow the BIDS ``task-programming`` naming convention (for example
 ``sub-01_ses-20250115_task-programming_run-01_events.tsv``).
 
 ----
@@ -146,9 +146,9 @@ Report Contents
 ----------------
 
 The exported Word/PDF follows the same section order as the
-:doc:`longitudinal summary on output_format <output_format>`.  Example
-screenshots from a multi-session export (synthetic documentation data only;
-not a real clinical case):
+:doc:`longitudinal summary on output_format <output_format>`. Example
+screenshots from a multi-session export use synthetic documentation data only,
+not a real clinical case:
 
 Title
 ^^^^^

docs/output_format.rst

@@ -9,9 +9,9 @@ structure of the exported reports.
 TSV Data File
 -------------
 
-All session data is stored as a **tab-separated values** (``.tsv``) file.
-One file is created per session; rows are appended in real-time as entries
-are recorded.
+All session data is stored as a **tab-separated values** (``.tsv``) file. One
+file is created per session; rows are appended in real time as entries are
+recorded.
 
 Filename Convention
 ^^^^^^^^^^^^^^^^^^^
@@ -22,10 +22,10 @@ Filenames follow the `BIDS <https://bids.neuroimaging.io/>`_ pattern::
 
 The ``task`` segment depends on which workflow created the file:
 
-* **Complete Workflow** — ``task-programming`` (stimulation parameters, clinical
+* **Complete Workflow**: ``task-programming`` (stimulation parameters, clinical
   and session scales, notes).
-* **Annotations-only Workflow** — ``task-annotations`` (timestamped text annotations
-  only; dedicated column schema — see *Annotations-only TSV columns* below).
+* **Annotations-only Workflow**: ``task-annotations`` (timestamped text
+  annotations only; see *Annotations-only TSV columns* below).
 
 Examples::
 
@@ -36,7 +36,8 @@ Columns
 ^^^^^^^
 
 The schema tables below are generated from the code-level constants in
-``dbs_annotator.config``. This keeps the docs and writer implementation in sync.
+``dbs_annotator.config``. This keeps the docs and writer implementation in
+sync.
 
 .. include:: _generated/tsv_schema.inc.rst
 
@@ -63,6 +64,12 @@ The programming-session example used in the report section below is stored as
 Each scale is stored on its own row; rows sharing the same ``block_ID`` belong
 to one baseline (Step 1) or stimulation configuration (Step 3 **Insert**).
 
+.. note::
+
+   **Illustrative example only.** The example TSV shown below is a synthetic
+   documentation example. It is not derived from, and does not represent, any
+   real patient or clinical encounter.
+
 `Download the example TSV`_
 
 .. _Download the example TSV:
@@ -94,11 +101,10 @@ at export time.
 
 .. note::
 
-   **Illustrative examples only.**  The report screenshots and sample data
-   files shown below are synthetic documentation materials.  They are not
-   derived from, and do not represent, any real patient, clinical encounter,
-   or identifiable health information.  They are provided solely to
-   demonstrate report layout and export format.
+   **Illustrative examples only.** The report screenshots and sample data files
+   shown below are synthetic documentation materials. They are not derived from,
+   and do not represent, any real patient or clinical encounter.
+
 
 Single-Session Report
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -186,8 +192,7 @@ Sections (in order, selected at export time):
       :class: screenshot-native
 
 3. **Session Data** *(optional)* — session-scale timeline chart and/or
-   combined table across all sessions.  The table's first column is the entry
-   **date**; the best entry per session is highlighted.
+   combined table across all sessions. The best entry per session is highlighted.
 
    * **Session Data Graph** — one subplot per session scale, with data from
      **all** loaded ``task-programming`` files combined so you can compare