Fix Sphinx documentation warnings

Co-authored-by: Junie <junie@jetbrains.com>

doc/api_reference.rst

@@ -5,16 +5,6 @@ API Reference
 This page provides an auto-generated reference of all DAMARIS classes, functions, and modules.
 It is built from docstrings using Sphinx autodoc and autosummary.
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Modules:
-
-   damaris/data
-   damaris/experiments
-   damaris/gui
-   damaris/tools
-
-
 Data Module
 ===========
 

doc/conf.py

@@ -33,7 +33,7 @@ bibtex_bibstyles = ['numeric']
 bibtex_citestyle = 'numeric'
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'damaris/**']
 
 language = 'en'
 
@@ -42,4 +42,4 @@ language = 'en'
 
 #html_theme = 'alabaster'
 html_theme = 'sphinx_rtd_theme'
-html_static_path = ['_static']
+html_static_path = []

src/damaris/data/DataPool.py

@@ -15,7 +15,7 @@ class DataPool(collections.abc.MutableMapping):
     
     # supports translation from dictionary keys to pytables hdf node names
     # taken from: Python Ref Manual Section 2.3: Identifiers and keywords
-    # things are always prefixed by "dir_" or "dict_"
+    # things are always prefixed by ``dir_`` or ``dict_``
     """
     translation_table=""
     for i in range(256):
@@ -118,44 +118,28 @@ class DataPool(collections.abc.MutableMapping):
         This method serializes the entire content of the data pool into an HDF5 file, creating
         appropriate groups and arrays based on the keys and values stored in the data pool.
         Nested storage paths are supported, and group or array names are
-        converted into valid HDF5 names. Paths are prepended with "dir_", results with "dict_".
+        converted into valid HDF5 names. Paths are prepended with ``dir_``, results with ``dict_``.
-        If duplicate names arise, extensions (like `_001`, `_002`)
+        If duplicate names arise, extensions (like ``_001``, ``_002``)
         are appended to ensure uniqueness.
 
-        Parameters:
+        :param hdffile: HDF5 file path or an open ``tables.File`` object.
-        hdffile : str | bytes | tables.File
+        :type hdffile: str, bytes, or tables.File
-            Path to the HDF5 file or an already open `tables.File` object where the
+        :param where: Root HDF5 group path under which data is stored.
-            data should be written. Strings or bytes are interpreted as file paths.
+        :type where: str
+        :param name: Name of the root HDF5 group. Defaults to ``data_pool``.
+        :type name: str
+        :param complib: Compression library; ``None`` disables compression.
+        :type complib: str or None
+        :param complevel: Compression level; unused when ``complib`` is ``None``.
+        :type complevel: int or None
+        :param incremental: If true, write only keys changed since the last write.
+        :type incremental: bool
+        :param write_interval: Time interval in seconds between periodic writes.
+        :type write_interval: int
+        :raises Exception: If ``hdffile`` is neither a string nor a ``tables.File`` object.
 
-        where : str, optional
+        Notes
-            The root HDF5 group path under which the data pool will be stored.
+        -----
-            Defaults to "/".
-
-        name : str, optional
-            The name of the root HDF5 group under which the data pool is saved.
-            Defaults to "data_pool".
-
-        complib : str, optional
-            Compression library to be used when creating HDF5 arrays. Optional, defaults
-            to None, meaning no compression is applied.
-
-        complevel : int, optional
-            Compression level to use when applying compression. Has no effect if `complib`
-            is set to None.
-
-        incremental : bool, optional
-            If True, only write keys that have been modified since the last write (dirty keys).
-            If False, write all keys. Defaults to False.
-
-        write_interval : int, optional
-            Time interval in seconds between periodic writes.
-            Defaults to 0.
-
-        Raises:
-        Exception
-            If `hdffile` is neither a string nor a valid `tables.File` object.
-
-        Notes:
         - This method assumes that the content of the data pool does not change during the
           write operation.
         - Keys in the data pool starting with "__" (double underscores) are skipped.

src/damaris/gui/logging_utils.py

@@ -2,7 +2,8 @@
 """
 Unified logging for DAMARIS.
 
-Provides:
+Provides these components:
+
 - FileTailerHandler: reads new lines from the backend log file and emits them
   as logging records into the damaris.backend logger.
 - LogDispatcher: a logging.Handler that dispatches records to both a GTK