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

help and electrode in rtd

Author: Lucia-Poma

CHANGELOG.md

@@ -13,8 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   and session scales settings dialogs, and regenerated workflow captures at
   native resolution (HiDPI-aware screen grab, improved PNG settings).
 - ``docs/_static/custom.css``: full-width RTD content; ``screenshot-full`` (wizard
-  steps) and ``screenshot-native`` (home, dialogs, electrode diagram) capped at
-  each PNG's intrinsic width so dialogs are not upscaled on wide screens.
+  steps) and ``screenshot-native`` (home, dialogs) capped at each PNG's intrinsic
+  width so dialogs are not upscaled on wide screens.
 - ``COPYRIGHT_HOLDERS`` and ``APP_LICENSE_NAME`` in ``config.py`` (shared with
   documentation).
 
@@ -35,9 +35,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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
+  UI is already visible in the Step 1 screenshot).
 
 ### Fixed
 
+- 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
+  a misleading “no updates” dialog.
 - Electrode diagram export: E0–En labels no longer clipped on the left in PNG
   output (wider label box and export left padding in ``ElectrodeCanvas``).
 - Docs screenshot pipeline: Windows ``QPixmap.save``/PNG compression; trim

docs/_static/custom.css

@@ -19,7 +19,7 @@
 }
 
 /*
- * Dialogs, home screen, electrode diagram, etc.
+ * Dialogs, home screen, and other partial captures.
  * Never upscale beyond the PNG's intrinsic width; shrink only on narrow viewports.
  */
 .rst-content img.screenshot-native,

docs/_static/electrode_diagram.png

@@ -6,47 +6,49 @@ General
 
 **Does the application require an internet connection?**
 
-No : session recording, editing, and export work fully
-offline and only read and write local files.  Optionally, the application can
-contact the public GitHub *releases* API (about once per day when enabled) to
-see whether a newer build is published; that request does not include patient
-or session content.  If the network is unavailable or the check fails, the app
-continues without blocking.  You can turn off automatic update checks from
-**Help** (or from the opt-out on an update notification).
+No: session recording, editing, and export work fully offline and only read and
+write local files.  Optionally, the application can contact the public GitHub
+*releases* API (about once per day when enabled) to see whether a newer build
+is published; that request does not include patient or session content.  If the
+network is unavailable or the check fails, the app continues without blocking.
+You can turn off automatic update checks from Help (or from the opt-out on an
+update notification).
 
 **Is my patient data sent anywhere?**
 
-No.  All data stays on your local machine.  No telemetry, no cloud sync.
+No.  All data stays on your local machine or the folder you chose when starting
+a session.  No telemetry, no cloud sync.
 
 **How does the automatic update checker work?**
 
 When automatic checks are enabled, the app compares your installed version with
 published releases on the upstream GitHub repository (including pre-releases
 when they are the newest applicable tag), and notifies you if a strictly newer
-semver is available.  Only one candidate release is considered—the highest
-version above yours.  Update checks run in the background, do not block startup,
-and are skipped silently on errors.  Use **Help** to toggle “Automatically check
-for updates”, or disable them from the checkbox on the update dialog if you do
-not want further automatic notifications.
+semver is available.  Only one candidate release is considered: the highest
+version above yours.  Update checks run in the background, do not block
+startup, and are skipped silently on errors.  Use Help to toggle
+"Automatically check for updates", or disable them from the checkbox on the
+update dialog if you do not want further automatic notifications.
 
 **Which DBS systems are supported?**
 
 The application is system-agnostic for data recording.  Electrode visualisation
 supports leads from Medtronic (including Percept PC / RC), Abbott (Infinity),
-Boston Scientific (Vercise) and PINS families.
-If your lead is not listed, use the closest equivalent or contact the
-development team to request it be added.
+Boston Scientific (Vercise), and PINS families.  If your lead is not listed,
+use the closest equivalent or contact the development team to request it be
+added.
 
 **Can I use the application on a shared clinical workstation?**
 
-Yes.  The application is easily installable and does not require installation or registry entries.
+Yes.  The application installs per user without requiring administrator rights
+for day-to-day use.  Session files are plain TSV files in folders you choose.
 
 ----
 
 Files & Data
 ------------
 
-**Where are my data files saved?**
+**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.
@@ -56,8 +58,8 @@ never writes files outside that folder.
 Yes.  In Excel: *File → Open*, select the ``.tsv`` file, and in the Text Import
 Wizard choose **Tab** as the delimiter.
 
-Alternatively, double-click the file — Windows may open it in Excel
-automatically if Excel is installed.
+Alternatively, double-click the file; Windows may open it in Excel automatically
+if Excel is installed.
 
 **Can I edit the TSV file manually?**
 
@@ -66,20 +68,14 @@ You can, but be careful:
 * Do not change column headers.
 * Do not delete or reorder rows.
 * Do not change the ``is_initial`` values.
-* Save as Tab-delimited TSV, not as ``.xlsx``.
+* Save as tab-delimited TSV, not as ``.xlsx``.
 
 **What happens if the application crashes mid-session?**
 
-All entries are written to disk immediately as they are recorded in the TSV file.  You will not
-lose any data that was successfully recorded before the crash.  Reopen the
-application, start a new session pointing to the same folder, and the existing
-file will be detected.
-
-**Can I merge two TSV files from the same session?**
-
-Manually: open both files in a text editor and copy the rows from the second
-file (excluding the header row) to the end of the first.  Make sure session IDs
-are unique after merging.
+All entries are written to disk immediately as they are recorded in the TSV
+file.  You will not lose any data that was successfully recorded before the
+crash.  Reopen the application, start a new session pointing to the same folder,
+and the existing file will be detected.
 
 ----
 
@@ -107,11 +103,10 @@ without the full entry table, select **Session Data Graph** only.
 
 **Where do the timeline charts in reports come from?**
 
-Session and longitudinal exporters build PNG charts with matplotlib
-(``report_chart_utils``).  **Session Data Graph** plots session-scale values
-(0–10) against ``block_ID`` (configuration index).  **Sessions Overview** in the
-longitudinal report adds a separate chart of baseline clinical scales across
-loaded session files.
+Session and longitudinal exporters build PNG charts with matplotlib.
+**Session Data Graph** plots session-scale values (0–10 by default) against
+``block_ID`` (configuration index).  **Sessions Overview** in the longitudinal
+report adds a separate chart of clinical scales across loaded session files.
 
 **Word export works but PDF export fails.**
 
@@ -134,8 +129,8 @@ 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.
+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.**
 
@@ -156,7 +151,7 @@ Check that:
 The longitudinal report requires at least one session file with recorded scale
 values (``scale_name`` and ``scale_value`` columns populated) in
 ``is_initial = 0`` rows.  If your files only contain initial entries, the
-dialog cannot compute best-entry highlighting — proceed by clicking OK without
+dialog cannot compute best-entry highlighting; proceed by clicking OK without
 making any selection.
 
 ----

docs/faq.rst

@@ -73,13 +73,11 @@ This step records the **baseline** state at the beginning of the session
 Electrode Model
 ^^^^^^^^^^^^^^^
 
-Select the implanted electrode model from the dropdown.  The application
-supports all common Medtronic Percept, Abbott, and Boston Scientific leads.
-An interactive diagram of the selected electrode is displayed immediately.
-
-.. image:: _static/electrode_diagram.png
-   :alt: Interactive electrode contact diagram
-   :class: screenshot-native
+Select the implanted electrode model from the **Model** dropdown.  Optionally,
+pick a **Manufacturer** to narrow the list.  The application supports common DBS
+leads from Medtronic, Abbott, Boston Scientific, and other vendors.  The Step 1
+screenshot above shows the interactive diagram (example:
+Medtronic SenSight B33005, left and right hemispheres).
 
 Contact Selection
 ^^^^^^^^^^^^^^^^^

docs/workflow_session.rst

@@ -21,6 +21,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
+    "certifi>=2024.0.0",
     "tzdata>=2026.2",
     "pandas>=2.1",
     "python-docx>=1.1",

pyproject.toml

@@ -24,17 +24,19 @@
 
 import json
 import logging
+import ssl
 import urllib.error
 import urllib.request
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 from typing import Any, cast
 
+import certifi
 from packaging.version import InvalidVersion, Version
 from PySide6.QtCore import QObject, QRunnable, QSettings, QThreadPool, Signal
 
-from .. import __version__
+from ..version import get_version
 
 logger = logging.getLogger(__name__)
 
@@ -49,6 +51,11 @@
 _MAX_RELEASE_PAGES = 5
 
 
+def _ssl_context() -> ssl.SSLContext:
+    """CA bundle for HTTPS in packaged apps (Briefcase MSI/ZIP on Windows)."""
+    return ssl.create_default_context(cafile=certifi.where())
+
+
 @dataclass(frozen=True)
 class ReleaseInfo:
     """Metadata for a GitHub release that is newer than the running app."""
@@ -145,10 +152,12 @@ def _request(self, url: str) -> urllib.request.Request:
 
     def _urlopen_json(self, url: str) -> object:
         request = self._request(url)
-        with urllib.request.urlopen(request, timeout=self._timeout) as response:
+        with urllib.request.urlopen(
+            request, timeout=self._timeout, context=_ssl_context()
+        ) as response:
             return json.loads(response.read().decode("utf-8"))
 
-    def _fetch_releases_page(self, page: int) -> list[dict] | None:
+    def _fetch_releases_page(self, page: int) -> list[dict]:
         url = (
             f"https://api.github.com/repos/{self._repo}/releases"
             f"?per_page={_RELEASES_PAGE_SIZE}&page={page}"
@@ -157,12 +166,9 @@ def _fetch_releases_page(self, page: int) -> list[dict] | None:
             payload = self._urlopen_json(url)
         except urllib.error.HTTPError as exc:
             if exc.code == 404:
-                logger.debug(
-                    "No GitHub releases list for %s (HTTP %s); treat as no update",
-                    self._repo,
-                    exc.code,
-                )
-                return None
+                raise RuntimeError(
+                    f"GitHub releases API returned 404 for {self._repo}."
+                ) from exc
             raise
         if not isinstance(payload, list):
             return []
@@ -172,26 +178,26 @@ def _fetch_all_releases(self) -> list[dict]:
         merged: list[dict] = []
         for page in range(1, _MAX_RELEASE_PAGES + 1):
             batch = self._fetch_releases_page(page)
-            if batch is None:
-                return []
             merged.extend(batch)
             if len(batch) < _RELEASES_PAGE_SIZE:
                 break
         return merged
 
     def _fetch_newest_applicable_release(self) -> ReleaseInfo | None:
         """Return single newest published release with version *>* local."""
-        payloads = self._fetch_all_releases()
-        if not payloads:
-            return None
-
         local = _parse_version(self._current_version)
         if local is None:
-            logger.debug(
-                "Skipping update comparison; local version not PEP 440: %r",
-                self._current_version,
+            raise ValueError(
+                f"Installed version {self._current_version!r} is not a valid "
+                "PEP 440 version."
+            )
+
+        payloads = self._fetch_all_releases()
+        if not payloads:
+            raise RuntimeError(
+                f"No published releases returned for {self._repo} "
+                "(empty list or network issue)."
             )
-            return None
 
         best_remote: Version | None = None
         best_payload: dict | None = None
@@ -249,7 +255,7 @@ def __init__(
     ) -> None:
         super().__init__(parent)
         self._repo = repo
-        self._current_version = current_version or __version__
+        self._current_version = current_version or get_version()
         self._cooldown = cooldown
         self._timeout = timeout
         self._settings = QSettings()

src/dbs_annotator/utils/updater.py

@@ -28,7 +28,7 @@
     QSpacerItem,
     QStackedWidget,
     QStyle,
-    QTextEdit,
+    QTextBrowser,
     QVBoxLayout,
     QWidget,
 )
@@ -109,7 +109,7 @@ def __init__(self, app):
 
         # Background update check. Runs once per cooldown window (24h by
         # default); offline / rate-limited failures are logged silently.
-        self._update_checker = UpdateChecker(parent=self)
+        self._update_checker = UpdateChecker(current_version=APP_VERSION, parent=self)
         self._update_checker.update_available.connect(self._on_update_available)
         # Defer slightly so the window is painted before any dialog appears.
         QTimer.singleShot(1500, self._run_deferred_update_check)
@@ -368,19 +368,34 @@ def _update_theme_button_icon(self) -> None:
         else:
             self.theme_toggle_btn.setText("🌙")  # Moon = will switch to dark
 
+    @staticmethod
+    def _help_link(href: str, label: str, *, dark: bool) -> str:
+        """Styled, readable hyperlink for the Help dialog (light vs dark theme)."""
+        color = "#93c5fd" if dark else "#b45309"
+        safe_href = html.escape(href, quote=True)
+        safe_label = html.escape(label)
+        return (
+            f'<a href="{safe_href}" style="color: {color}; '
+            f'text-decoration: underline;">{safe_label}</a>'
+        )
+
     def _help_dialog_html(self) -> str:
         """HTML body for the Help / About dialog."""
         year = datetime.now().year
-        repo = html.escape(APP_REPOSITORY_URL)
-        issues = html.escape(APP_ISSUES_URL)
-        email = html.escape(UPDATE_FEEDBACK_EMAIL)
+        dark = get_theme_manager().is_dark_mode()
+        repo_url = APP_REPOSITORY_URL
+        issues_url = APP_ISSUES_URL
+        mailto = f"mailto:{UPDATE_FEEDBACK_EMAIL}"
+        repo = self._help_link(repo_url, repo_url, dark=dark)
+        issues = self._help_link(issues_url, issues_url, dark=dark)
+        email = self._help_link(mailto, UPDATE_FEEDBACK_EMAIL, dark=dark)
         return f"""
         <h3>General Overview</h3>
         <p>The main use of {html.escape(APP_NAME)} is a <b>standard pipeline</b> for
         DBS <b>programming sessions</b>: baseline setup, session scales, and
         real-time recording of each stimulation configuration you test in clinic.</p>
         <ol>
-            <li><b>File &amp; patient setup</b>: choose where to save the session file
+            <li><b>File setup</b>: choose where to save the session file
                 (BIDS-style name).</li>
             <li><b>Initial configuration</b>: electrode model, starting stimulation
                 parameters, and baseline clinical scales.</li>
@@ -412,9 +427,9 @@ def _help_dialog_html(self) -> str:
         <h3>Credits &amp; support</h3>
         <p><b>Publisher:</b> {html.escape(ORGANIZATION_PUBLISHER)}<br/>
         <b>Lead developer:</b> {html.escape(APP_LEAD_AUTHOR)}</p>
-        <p><b>Repository:</b> <a href="{repo}">{repo}</a><br/>
-        <b>Issues:</b> <a href="{issues}">{issues}</a><br/>
-        <b>Contact:</b> <a href="mailto:{email}">{email}</a></p>
+        <p><b>Repository:</b> {repo}<br/>
+        <b>Issues:</b> {issues}<br/>
+        <b>Contact:</b> {email}</p>
         """
 
     def _show_info_dialog(self) -> None:
@@ -431,10 +446,10 @@ def _show_info_dialog(self) -> None:
         title_label.setAlignment(Qt.AlignmentFlag.AlignCenter)
         layout.addWidget(title_label)
 
-        # Description
-        desc_text = QTextEdit()
-        desc_text.setReadOnly(True)
+        desc_text = QTextBrowser()
+        desc_text.setOpenExternalLinks(True)
         desc_text.setHtml(self._help_dialog_html())
+        desc_text.anchorClicked.connect(QDesktopServices.openUrl)
 
         layout.addWidget(desc_text)