final details

Author: bruAristimunha

docs/source/conf.py

@@ -322,6 +322,22 @@ def linkcode_resolve(domain, info):
 """
 
 
+BASE_DATASET_TEMPLATE = """{notice}.. _api_eegdash_challenge_dataset:
+
+.. currentmodule:: eegdash.dataset
+
+EEGChallengeDataset
+===================
+
+.. autoclass:: eegdash.dataset.EEGChallengeDataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+
+"""
+
+
 def _write_if_changed(path: Path, content: str) -> bool:
     """Write ``content`` to ``path`` if it differs from the current file."""
     existing = path.read_text(encoding="utf-8") if path.exists() else None
@@ -548,6 +564,11 @@ def _generate_dataset_docs(app) -> None:
     if _write_if_changed(index_path, index_content):
         LOGGER.info("[dataset-docs] Updated %s", index_path.relative_to(app.srcdir))
 
+    base_content = BASE_DATASET_TEMPLATE.format(notice=AUTOGEN_NOTICE)
+    base_path = dataset_dir / "eegdash.dataset.EEGChallengeDataset.rst"
+    if _write_if_changed(base_path, base_content):
+        LOGGER.info("[dataset-docs] Updated %s", base_path.relative_to(app.srcdir))
+
     generated_paths: set[Path] = set()
     for name in dataset_names:
         title = f"eegdash.dataset.{name}"

docs/source/user_guide.rst

@@ -2,15 +2,18 @@
 
 :html_theme.sidebar_secondary.remove: true
 
+.. currentmodule:: eegdash.api
+
+
 User Guide
 ==========
 
-This guide provides a comprehensive overview of the :mod:`eegdash` library, focusing on its core data access object, :class:`eegdash.api.EEGDashDataset`. You will learn how to use this object to find, access, and manage EEG data for your research and analysis tasks.
+This guide provides a comprehensive overview of the :mod:`eegdash` library, focusing on its core data access object, :class:`~eegdash.api.EEGDashDataset`. You will learn how to use this object to find, access, and manage EEG data for your research and analysis tasks.
 
 The EEGDash Object
 ------------------
 
-While :class:`eegdash.api.EEGDashDataset` is the main tool for loading data for machine learning, the :class:`eegdash.api.EEGDash` object provides a lower-level interface for directly interacting with the metadata database. It is useful for exploring the available data, performing complex queries, or managing metadata records.
+While :class:`~eegdash.api.EEGDashDataset` is the main tool for loading data for machine learning, the :class:`~eegdash.api.EEGDash` object provides a lower-level interface for directly interacting with the metadata database. It is useful for exploring the available data, performing complex queries, or managing metadata records.
 
 Initializing EEGDash
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -45,20 +48,20 @@ EEGDash vs. EEGDashDataset
 
 It's important to understand the distinction between these two objects:
 
--   :class:`eegdash.api.EEGDash`: Use this for querying and managing metadata. It returns a list of dictionaries, where each dictionary is a record from the database.
--   :class:`eegdash.api.EEGDashDataset`: Use this when you need to load EEG data for analysis or machine learning. It returns a PyTorch-compatible dataset object where each item can load the actual EEG signal.
+-   :class:`~eegdash.api.EEGDash`: Use this for querying and managing metadata. It returns a list of dictionaries, where each dictionary is a record from the database.
+-   :class:`~eegdash.api.EEGDashDataset`: Use this when you need to load EEG data for analysis or machine learning. It returns a PyTorch-compatible dataset object where each item can load the actual EEG signal.
 
-In general, you will use :class:`eegdash.api.EEGDashDataset` for most of your data loading needs.
+In general, you will use :class:`~eegdash.api.EEGDashDataset` for most of your data loading needs.
 
 The EEGDashDataset Object
 -------------------------
 
-The :class:`eegdash.api.EEGDashDataset` is the primary entry point for working with EEG recordings in :mod:`eegdash`. It acts as a high-level interface that allows you to query a metadata database and load corresponding EEG data, either from a remote source or from a local cache.
+The :class:`~eegdash.api.EEGDashDataset` is the primary entry point for working with EEG recordings in :mod:`eegdash`. It acts as a high-level interface that allows you to query a metadata database and load corresponding EEG data, either from a remote source or from a local cache.
 
 Initializing EEGDashDataset
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To get started, you need to create an instance of :class:`eegdash.api.EEGDashDataset`. The two most important parameters are ``cache_dir`` and ``dataset``.
+To get started, you need to create an instance of :class:`~eegdash.api.EEGDashDataset`. The two most important parameters are ``cache_dir`` and ``dataset``.
 
 - ``cache_dir``: This is the local directory where ``eegdash`` will store downloaded data.
 - ``dataset``: The identifier of the dataset you want to work with (e.g., ``"ds002718"``).
@@ -82,7 +85,7 @@ This will create a dataset object containing all recordings from ``ds002718``. T
 Querying for Specific Data
 --------------------------
 
-:class:`eegdash.api.EEGDashDataset` offers powerful filtering capabilities, allowing you to select a subset of recordings based on various criteria. You can filter by task, subject, session, or run.
+:class:`~eegdash.api.EEGDashDataset` offers powerful filtering capabilities, allowing you to select a subset of recordings based on various criteria. You can filter by task, subject, session, or run.
 
 Filtering by Task
 ~~~~~~~~~~~~~~~~~
@@ -164,11 +167,11 @@ For more complex queries, you can pass a MongoDB-style query dictionary directly
 Working with Local Data (Offline Mode)
 --------------------------------------
 
-:mod:`eegdash` also supports working with local data that you have already downloaded or manage separately. By setting ``download=False``, you can instruct :class:`eegdash.api.EEGDashDataset` to use local BIDS-compliant data instead of accessing the database or remote storage.
+:mod:`eegdash` also supports working with local data that you have already downloaded or manage separately. By setting ``download=False``, you can instruct :class:`~eegdash.api.EEGDashDataset` to use local BIDS-compliant data instead of accessing the database or remote storage.
 
 To use this feature, your data must be organized in a BIDS-like structure within your ``cache_dir``. For example, if your ``cache_dir`` is ``./eeg_data`` and your dataset is ``ds002718``, the files should be located at ``./eeg_data/ds002718/``.
 
-Here is how to use :class:`eegdash.api.EEGDashDataset` in offline mode:
+Here is how to use :class:`~eegdash.api.EEGDashDataset` in offline mode:
 
 .. code-block:: python
 
@@ -186,7 +189,7 @@ When ``download=False``, :mod:`eegdash` will scan the specified directory for EE
 Accessing Data from the Dataset
 -------------------------------
 
-Once you have your :class:`eegdash.api.EEGDashDataset` object, you can access individual recordings as if it were a list. Each item in the dataset is an ``EEGDashBaseDataset`` object, which contains the metadata and methods to load the actual EEG data.
+Once you have your :class:`~eegdash.api.EEGDashDataset` object, you can access individual recordings as if it were a list. Each item in the dataset is an :class:`~eegdash.data_utils.EEGDashBaseDataset` object, which contains the metadata and methods to load the actual EEG data.
 
 .. code-block:: python
 

examples/eeg2025/tutorial_challenge_2.py

@@ -51,7 +51,8 @@
 # Contents of this start kit
 # --------------------------
 # .. note:: If you need additional explanations on the
-#    :class:`eegdash.dataset.EEGChallengeDataset` class, dataloading,
+#    :doc:`EEGChallengeDataset
+#    </api/dataset/eegdash.dataset.EEGChallengeDataset>` class, dataloading,
 #    `braindecode <https://braindecode.org/stable/models/models_table.html>`__'s
 #    deep learning models, or brain decoding in general, please refer to the
 #    start-kit of challenge 1 which delves deeper into these topics.
@@ -142,7 +143,7 @@
 # Define local path and (down)load the data
 # -----------------------------------------
 # In this challenge 2 example, we load the EEG 2025 release using
-# :class:`eegdash.dataset.EEGChallengeDataset`.
+# :doc:`EEGChallengeDataset </api/dataset/eegdash.dataset.EEGChallengeDataset>`.
 # **Note:** in this example notebook, we load the contrast change detection task from one mini release only as an example. Naturally, you are encouraged to train your models on all complete releases, using data from all the tasks you deem relevant.
 
 ######################################################################

examples/eeg2025/tutorial_eegdash_offline.py

@@ -5,7 +5,7 @@
 Many HPC clusters restrict or block network access. It's common to have
 dedicated queues for internet-enabled jobs that differ from GPU queues.
 This tutorial shows how to use :doc:`EEGChallengeDataset
-<api/dataset/eegdash.dataset.EEGChallengeDataset>` offline once a dataset is
+</api/dataset/eegdash.dataset.EEGChallengeDataset>` offline once a dataset is
 present on disk.
 """
 
@@ -17,8 +17,8 @@
 
 
 # We'll use Release R2 as an example (HBN subset).
-# :class:`eegdash.dataset.EEGChallengeDataset` uses a suffixed cache folder for
-# the competition data (e.g., "-bdf-mini").
+# :doc:`EEGChallengeDataset </api/dataset/eegdash.dataset.EEGChallengeDataset>`
+# uses a suffixed cache folder for the competition data (e.g., "-bdf-mini").
 release = "R2"
 dataset_id = RELEASE_TO_OPENNEURO_DATASET_MAP[release]
 task = "RestingState"
@@ -54,7 +54,8 @@
 # ---------------------------
 # Once the data is cached locally, you can interact with it without needing an
 # internet connection. The key is to instantiate your dataset object with the
-# ``download=False`` flag. This tells :class:`eegdash.dataset.EEGChallengeDataset`
+# ``download=False`` flag. This tells :doc:`EEGChallengeDataset
+# </api/dataset/eegdash.dataset.EEGChallengeDataset>`
 # to look for data in the ``cache_dir`` instead of trying to connect to the
 # database or S3.
 
@@ -80,9 +81,9 @@
 # ----------------------------------
 # Even without a database connection, you can still filter your dataset by
 # BIDS entities like subject, session, or task. When ``download=False``,
-# :class:`eegdash.dataset.EEGChallengeDataset` uses the BIDS directory structure
-# and filenames to apply these filters. This example shows how to load data for
-# a specific subject from the local cache.
+# :doc:`EEGChallengeDataset </api/dataset/eegdash.dataset.EEGChallengeDataset>`
+# uses the BIDS directory structure and filenames to apply these filters. This
+# example shows how to load data for a specific subject from the local cache.
 
 ds_offline_sub = EEGChallengeDataset(
     cache_dir=cache_dir,