Merge pull request #110 from Brain-Modulation-Lab/feat/improving-readthedocs

Feat/improving readthedocs

Author: Lucia-Poma

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   width so dialogs are not upscaled on wide screens.
 - ``COPYRIGHT_HOLDERS`` and ``APP_LICENSE_NAME`` in ``config.py`` (shared with
   documentation).
+- ``APP_MAINTAINER`` in ``config.py``; **Help** dialog lists **Maintainer: Richard
+  Köhler** under lead developer.
 
 ### Changed
 
@@ -26,20 +28,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Annotations-only file step header title: **Clinical Annotations Setup** (was
   "Output File").
 - Home screen buttons: **Complete Workflow** and **Annotations-only Workflow**.
-- Read the Docs: installation aligned with README; workflow pages renamed
-  (**Complete Workflow**, **Annotation-only Workflow**); ``workflow_session.rst``
-  documents per-session scales (**−** / **+**, settings dialogs);
-  ``longitudinal_report.rst`` and ``quickstart.rst`` specify ``task-programming``
-  BIDS files for longitudinal reports.
+- Annotations-only TSV column ``annotation`` renamed to ``notes`` (aligned with
+  the Complete Workflow); legacy files with an ``annotation`` header remain
+  readable and appendable.
+- Read the Docs: ``workflow_session.rst`` renamed to ``workflow_complete.rst``;
+  ``quickstart.rst`` documents launching the installed app (Start Menu / MSI /
+  install script), all three workflows in home-screen order, and links to the
+  full guides; ``index.rst`` Quick Overview matches the same order.
+- ``workflow_complete.rst``: Step 0 file setup (**Open** / **New**, Session ID /
+  Run ID); UI actions documented as **Insert** and **Close session**; only one
+  overview video at the top of the page.
+- ``workflow_annotations.rst``: dedicated ``task-notes`` schema (``date``, ``time``,
+  ``timezone``, ``notes``); no merge of multiple TSV files; **Insert** /
+  **Close Session**; overview video removed.
+- ``longitudinal_report.rst``: single overview video at the top; **Create
+  Longitudinal Report** button naming.
+- ``output_format.rst``: ``task-programming`` vs ``task-notes`` / annotations
+  workflow called out in filename convention; generated schema uses ``notes`` for
+  annotations-only files.
+- ``faq.rst``: TSV save path references Step 0 file setup.
+- README **What It Does** aligned with RTD (four Complete Workflow steps, three
+  workflows, link to ``workflow_complete.rst``); installation and Contributing
+  sections unchanged.
 - Documentation copyright: Massachusetts General Hospital, Wyss Center for Bio
   and Neuroengineering, and Charité Universitätsmedizin Berlin.
 - Screenshot capture uses the app's responsive window geometry (step 0 compact,
   steps 1+ full workflow) instead of a fixed 1600×1000 frame.
-- ``workflow_session.rst``: drop standalone ``electrode_diagram.png`` (electrode
+- ``workflow_complete.rst``: drop standalone ``electrode_diagram.png`` (electrode
   UI is already visible in the Step 1 screenshot).
 
 ### Fixed
 
+- Dependency audit: pin ``idna>=3.15`` (GHSA-65pc-fj4g-8rjx); allow ``idna`` in
+  ``exclude-newer-package`` so the fix is not blocked by the one-week cooldown.
 - Update checker: HTTPS uses the ``certifi`` CA bundle (fixes failed or empty
   GitHub API responses in Briefcase MSI/ZIP on Windows); compares against
   ``APP_VERSION``; empty or invalid release data surfaces as errors instead of

README.md

@@ -30,7 +30,6 @@ powershell -ExecutionPolicy Bypass -NoProfile -Command "irm https://raw.githubus
 
 ### macOS / Linux — shell install (curl / wget)
 
-
 ```sh
 curl -LsSf https://raw.githubusercontent.com/Brain-Modulation-Lab/DBSAnnotator/main/scripts/install.sh | sh
 ```
@@ -41,28 +40,52 @@ wget -qO- https://raw.githubusercontent.com/Brain-Modulation-Lab/DBSAnnotator/ma
 
 ## What It Does
 
-The application guides you through a DBS programming session in three steps:
+From the home screen you can start three workflows (full guide:
+[Read the Docs](https://brain-modulation-lab.github.io/DBSAnnotator/)):
+
+### Complete Workflow
+
+Four steps — stimulation parameters, clinical scales, session scales, and notes;
+data saved automatically after each entry:
+
+1. **Step 0 — File setup** — Open or create a programming-session TSV
+  (`sub-XX_ses-YYYYMMDD_task-programming_run-XX_events.tsv`); **New** asks for
+   Patient ID and Run ID (Session ID is today's date).
+2. **Step 1 — Initial Configuration** — Electrode model, baseline stimulation
+  parameters, and clinical scales.
+3. **Step 2 — Session Scale Selection** — Scales rated at each configuration
+  during programming (e.g. Tremor, Mood).
+4. **Step 3 — Active Recording** — Adjust parameters, rate scales, add notes;
+  click **Insert** to record an entry; export a Word/PDF report when finished.
+
+See `[docs/workflow_complete.rst](docs/workflow_complete.rst)` for the full
+step-by-step guide (screenshots, scale presets, and report sections).
+
+### Annotations-only Workflow
+
+Timestamped text notes only — no stimulation parameters or scale values.  Uses a
+dedicated TSV (`task-notes`) with columns `date`, `time`, `timezone`, and
+`notes`.  See `[docs/workflow_annotations.rst](docs/workflow_annotations.rst)`.
 
-1. **Initial Setup** — Select output file, electrode model, initial stimulation parameters, and baseline clinical scales
-2. **Session Scales** — Choose which scales to track during the session (Mood, Anxiety, Energy, etc.)
-3. **Active Recording** — Adjust stimulation parameters in real-time, record scale values at each timepoint, add notes, and export a clinical report
+### Create Longitudinal Report
 
-There is also a **Free Annotations** mode for quick timestamped text annotations without the full stimulation workflow.
+Combine multiple programming-session TSV files from the same subject into one
+comparative Word/PDF report.  See `[docs/longitudinal_report.rst](docs/longitudinal_report.rst)`.
 
 ### Key Features
 
+- **Clinical and session scale presets** for OCD, MDD, PD, ET, Dystonia, TS
+- **Timestamps aligned** notes, configuration parameters and scale scores
+- **Export to Word / PDF** with electrode diagrams, tables, and timeline charts
+- **BIDS-compliant file naming** for programming and annotations TSV files
 - **Electrode visualization** with interactive contact selection (supports directional leads)
-- **Clinical scale presets** for OCD, MDD, PD, ET
-- **BIDS-compliant file naming** (sub-XX_ses-YYYYMMDD_task-programming_run-XX_events.tsv)
-- **Export to Word** with electrode configuration images, clinical notes, and session data tables
 - **Dark/Light theme** toggle
-- **Timestamps aligned** with Medtronic Percept data (Eastern Time)
 
 ### Output Format
 
-Data is saved as TSV. The canonical schema is documented in
-`[docs/output_format.rst](docs/output_format.rst)` and auto-generated from the
-code-level constants in `dbs_annotator.config` to prevent drift.
+Programming and annotations data are saved as TSV. The canonical schema is
+documented in `[docs/output_format.rst](docs/output_format.rst)` and
+auto-generated from `dbs_annotator.config` to prevent drift.
 
 ## Contributing
 
@@ -160,9 +183,9 @@ uv run briefcase package windows -p zip    # avoids WiX; omit -p (MSI) when WiX
 
 **Windows Briefcase quirks:** keep `[tool.briefcase].version` in sync with `dbs_annotator.__version__` (Briefcase does not use Hatch’s dynamic `[project]` version). Bump both in one step with `uv run python scripts/release_prepare.py <version>` (or `--bump …`). If `briefcase build` fails at **“Setting stub app details”** / RCEdit with **“Unable to commit changes”**, exclude the repo or `build\` from real-time antivirus scanning and retry (see [Briefcase issue #1530](https://github.com/beeware/briefcase/issues/1530)).
 
-The Windows stub binary is named `**DBSAnnotator.exe`** (from `[tool.briefcase.app.dbs_annotator].formal_name`). After changing that field, run `**briefcase create windows app**` again (or delete `build\dbs_annotator\windows`) before `**briefcase build**`.
+The Windows stub binary is named `**DBSAnnotator.exe`** (from `[tool.briefcase.app.dbs_annotator].formal_name`). After changing that field, run `**briefcase create windows app`** again (or delete `build\dbs_annotator\windows`) before `**briefcase build**`.
 
-Icons for the **stub**, **MSI/ZIP**, and **Qt** (`QApplication` / window chrome) live under `**icons/logosimple/`**: `**logosimple.ico**`, `**logosimple.png**`, plus `**logosimple-{16,32,64,128,256,512}.png**` for **Linux system** (BeeWare copies them into the Freedesktop hicolor tree; all six are listed in the upstream `briefcase-linux-system-template`). `**logosimple.icns`** is for macOS (build with `iconutil` on a Mac; see `scripts/build_app_icons.py`). Configure with `icon = "icons/logosimple/logosimple"` in `pyproject.toml`. The repo-root `**icons/**` tree is a Briefcase `**sources**` entry and is shipped next to the app package; runtime lookup uses `resource_path()` (package dir, then `src/icons`, then repo-root `icons/`).
+Icons for the **stub**, **MSI/ZIP**, and **Qt** (`QApplication` / window chrome) live under `**icons/logosimple/`**: `**logosimple.ico`**, `**logosimple.png**`, plus `**logosimple-{16,32,64,128,256,512}.png**` for Linux system (BeeWare copies them into the Freedesktop hicolor tree; all six are listed in the upstream `briefcase-linux-system-template`). `**logosimple.icns**` is for macOS (build with `iconutil` on a Mac; see `scripts/build_app_icons.py`). Configure with `icon = "icons/logosimple/logosimple"` in `pyproject.toml`. The repo-root `**icons/**` tree is a Briefcase `**sources**` entry and is shipped next to the app package; runtime lookup uses `resource_path()` (package dir, then `src/icons`, then repo-root `icons/`).
 
 **Inventory (for packaging):**
 
@@ -171,7 +194,7 @@ Icons for the **stub**, **MSI/ZIP**, and **Qt** (`QApplication` / window chrome)
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | App type           | Qt **GUI** (`console_app` is false by default).                                                                                                                                             |
 | Heavy deps         | `PySide6`, `matplotlib`, `pandas`, `python-docx`, `docx2pdf` (Windows: `pywin32`; macOS: `appscript` via `docx2pdf`).                                                                       |
-| Data files         | JSON presets under `src/dbs_annotator/config/`; QSS and SVG under repo-root `**styles/`** (also a Briefcase `**sources**` entry); app icons under `**icons/logosimple/**` (Briefcase + Qt). |
+| Data files         | JSON presets under `src/dbs_annotator/config/`; QSS and SVG under repo-root `**styles/`** (also a Briefcase `**sources`** entry); app icons under `**icons/logosimple/**` (Briefcase + Qt). |
 | macOS entitlements | Add an entitlements plist only if you enable the Hardened Runtime and need extra capabilities (network is usually fine without custom entitlements).                                        |
 
 

docs/_generated/tsv_schema.inc.rst

@@ -95,6 +95,6 @@ Annotations-only TSV columns
    * - ``timezone``
      - string
      - Timezone abbreviation/offset at capture time.
-   * - ``annotation``
+   * - ``notes``
      - string
-     - Free-text annotation.
+     - Free-text note for this entry.

docs/api.rst

@@ -4,7 +4,7 @@ API Reference
 This page is generated automatically from the docstrings of the
 ``dbs_annotator`` package.  It is aimed at developers extending or embedding
 the application; clinicians and researchers should prefer the
-:doc:`quickstart` and :doc:`workflow_session` guides.
+:doc:`quickstart` and :doc:`workflow_complete` guides.
 
 The reference deliberately covers the **data, configuration, and control
 layers** of the application.  The Qt UI layers (``dbs_annotator.ui`` and

docs/faq.rst

@@ -50,8 +50,9 @@ Files & Data
 
 **Where are TSV files saved?**
 
-In the folder you selected in Step 0 of the Complete Workflow.  The application
-never writes files outside that folder.
+In the folder of the ``.tsv`` file you chose in **Step 0 — File setup** of the
+Complete Workflow (or in the Annotations-only Workflow).  The application never
+writes files outside that path.
 
 **Can I open the TSV files in Excel?**
 
@@ -127,11 +128,6 @@ you selected an electrode model in Step 1 before recording entries.
 Troubleshooting
 ---------------
 
-**The application does not start / shows a black window.**
-
-Try running it as administrator (right-click → *Run as administrator*).  This is
-sometimes needed on machines with strict execution policies.
-
 **The application is very slow on first launch.**
 
 Windows Defender or other antivirus software may be scanning the executable.

docs/index.rst

@@ -38,7 +38,7 @@ the **Wyss Center for Bio and Neuroengineering** (Geneva, Switzerland), and
    :maxdepth: 2
    :caption: User Guide
 
-   workflow_session
+   workflow_complete
    workflow_annotations
    longitudinal_report
    output_format
@@ -71,13 +71,14 @@ Quick Overview
      - Record stimulation parameters, clinical scales, and notes step-by-step.
        Export a structured report (Word / PDF) with tables, electrode diagrams,
        and session-scale timeline charts.
+   * - **Annotations-only Workflow**
+     - Quick timestamped text notes without the full stimulation workflow.
    * - **Longitudinal report**
      - Combine multiple session files into a single comparative document with
        overview tables, clinical and session-scale charts, electrode diagrams,
        and programming summaries.
-   * - **Annotation-only Workflow**
-     - Quick timestamped text notes without the full stimulation workflow.
    * - **BIDS-compliant output**
      - Data saved as ``sub-XX_ses-YYYYMMDD_task-programming_run-XX_events.tsv``.
-   * - **No installation required**
-     - The application ships as a single self-contained ``.exe`` (Windows).
+   * - **Self-contained desktop app**
+     - Packaged installers (``.msi``, ``.dmg``, ``.deb``); no separate Python
+       runtime required.

docs/longitudinal_report.rst

@@ -224,7 +224,6 @@ A table with one row per session showing:
 Tips
 ----
 
-* Load files in **chronological order** for the most readable report.
 * The report can be re-generated at any time — the source TSV files are never
   modified.
 * For very long longitudinal histories (> 10 sessions) consider splitting the

docs/output_format.rst

@@ -16,9 +16,16 @@ are recorded.
 Filename Convention
 ^^^^^^^^^^^^^^^^^^^
 
-The filename follows the `BIDS <https://bids.neuroimaging.io/>`_ specification::
+Filenames follow the `BIDS <https://bids.neuroimaging.io/>`_ pattern::
 
-   sub-<PatientID>_ses-<YYYYMMDD>_task-programming_run-<NN>_events.tsv
+   sub-<PatientID>_ses-<YYYYMMDD>_task-<TASK>_run-<NN>_events.tsv
+
+The ``task`` segment depends on which workflow created the file:
+
+* **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).
 
 Examples::
 
@@ -43,7 +50,7 @@ Row layout and ``block_ID``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Each **scale** is stored on its own row.  Rows that belong to the same
-recording event (one Step 1 baseline or one Step 3 **Record entry**) share the
+recording event (one Step 1 baseline or one Step 3 **Insert**) share the
 same ``block_ID``; stimulation parameters, ``date``, ``time``, ``timezone``,
 ``program_ID``, ``electrode_model``, and ``notes`` are repeated on every row of
 that block.  After each write, ``block_ID`` increments by one.
@@ -117,10 +124,6 @@ Example export
    :alt: Example single-session Word report (graph, table, electrode diagrams)
    :class: screenshot-native
 
-.. tip::
-   Add a representative screenshot as ``docs/_static/session_report_example.png``
-   (e.g. session data graph + table + electrode configuration section).
-
 Longitudinal Report
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -145,11 +148,6 @@ Example export
    :alt: Example longitudinal Word report (overview chart and session data)
    :class: screenshot-native
 
-.. tip::
-   Add a representative screenshot as
-   ``docs/_static/longitudinal_report_example.png`` (e.g. sessions overview with
-   clinical-scales chart and combined session data).
-
 ----
 
 Timestamps and timezone

docs/quickstart.rst

@@ -9,8 +9,18 @@ choosing the right workflow for your needs.
 Launching the Application
 --------------------------
 
-Double-click **DBSAnnotator.exe** (or the Desktop shortcut).  The main
-window opens, showing the **Home screen**.
+After :doc:`installation`, open **DBS Annotator** from your system's
+application launcher (the installed app, not a loose ``.exe`` in a download
+folder):
+
+* **Windows** — **Start** menu entry **DBS Annotator** (from the ``.msi``
+  installer or the PowerShell install script shortcut).
+* **macOS** — *Applications* after installing from the ``.dmg`` or install
+  script.
+* **Linux** — application menu after installing the ``.deb`` or install
+  script.
+
+The main window opens on the **Home screen**.
 
 .. image:: _static/home_screen.png
    :alt: Application home screen
@@ -32,6 +42,9 @@ From the home screen you can start one of three workflows:
    * - **Complete Workflow**
      - You are about to perform a DBS programming session and want to record
        stimulation parameters, clinical scales, and notes in real-time.
+   * - **Annotations-only Workflow**
+     - You only need timestamped text notes — no stimulation parameters or
+       clinical scale values.
    * - **Create Longitudinal Report**
      - You already have multiple programming-session TSV files from the same
        subject (BIDS example:
@@ -66,6 +79,6 @@ immediately and maintained between pages.
 Next Steps
 ----------
 
-* :doc:`workflow_session` — **Complete Workflow**
+* :doc:`workflow_complete` — **Complete Workflow**
+* :doc:`workflow_annotations` — **Annotations-only Workflow**
 * :doc:`longitudinal_report` — **Create Longitudinal Report**
-* :doc:`workflow_annotations` — **Annotation-only Workflow**