Merge pull request #153 from sccn/develop

last details about the documentation

Author: bruAristimunha

docs/prepare_summary_tables.py

@@ -1,4 +1,5 @@
 import glob
+import json
 from argparse import ArgumentParser
 from pathlib import Path
 from shutil import copyfile
@@ -7,6 +8,7 @@
 import pandas as pd
 import plotly.express as px
 import plotly.graph_objects as go
+from plotly.utils import PlotlyJSONEncoder
 from scipy.stats import gaussian_kde
 from table_tag_utils import wrap_tags
 
@@ -225,7 +227,7 @@ def _fmt_int(v):
             x_field: x_label,
         },
         color_discrete_map=MODALITY_COLOR_MAP,
-        title="Dataset Landscape",
+        title="",
         category_orders={
             "modality_label": [
                 label
@@ -263,7 +265,7 @@ def _fmt_int(v):
             size=14,
         ),
         title=dict(
-            text="Dataset Landscape",
+            text="",
             x=0.01,
             xanchor="left",
             y=0.98,
@@ -684,7 +686,7 @@ def main(source_dir: str, target_dir: str):
                     ),
                     margin=dict(l=120, r=40, t=80, b=80),
                     title=dict(
-                        text="Participant Distribution by Modality",
+                        text="",
                         x=0.01,
                         xanchor="left",
                         y=0.98,
@@ -694,25 +696,26 @@ def main(source_dir: str, target_dir: str):
                 )
                 # Add CSS and loading indicator for immediate proper sizing
                 kde_height = max(650, 150 * len(order))
-                html_content = fig_kde.to_html(
-                    full_html=False,
-                    include_plotlyjs=False,
-                    div_id="dataset-kde-modalities",
-                    config={
-                        "responsive": True,
-                        "displaylogo": False,
-                        "modeBarButtonsToRemove": ["lasso2d", "select2d"],
-                        "toImageButtonOptions": {
-                            "format": "png",
-                            "filename": "participant_kde",
-                            "height": {kde_height},
-                            "width": 1200,
-                            "scale": 2,
-                        },
+                plot_config = {
+                    "responsive": True,
+                    "displaylogo": False,
+                    "modeBarButtonsToRemove": ["lasso2d", "select2d"],
+                    "toImageButtonOptions": {
+                        "format": "png",
+                        "filename": "participant_kde",
+                        "height": kde_height,
+                        "width": 1200,
+                        "scale": 2,
                     },
+                }
+                fig_spec = fig_kde.to_plotly_json()
+                data_json = json.dumps(fig_spec.get("data", []), cls=PlotlyJSONEncoder)
+                layout_json = json.dumps(
+                    fig_spec.get("layout", {}), cls=PlotlyJSONEncoder
                 )
+                config_json = json.dumps(plot_config, cls=PlotlyJSONEncoder)
 
-                # Wrap with styling to ensure proper initial sizing
+                # Wrap with styling to ensure proper initial sizing and defer Plotly rendering
                 styled_html = f"""
 <style>
 #dataset-kde-modalities {{
@@ -721,8 +724,9 @@ def main(source_dir: str, target_dir: str):
     height: {kde_height}px !important;
     min-height: {kde_height}px;
     margin: 0 auto;
+    display: none;
 }}
-#dataset-kde-modalities .plotly-graph-div {{
+#dataset-kde-modalities.plotly-graph-div {{
     width: 100% !important;
     height: 100% !important;
 }}
@@ -736,28 +740,60 @@ def main(source_dir: str, target_dir: str):
 }}
 </style>
 <div class="kde-loading" id="kde-loading">Loading participant distribution...</div>
-{html_content}
+<div id="dataset-kde-modalities" class="plotly-graph-div"></div>
 <script>
-// Hide loading indicator once plot is rendered
-document.addEventListener('DOMContentLoaded', function() {{
-    const loading = document.getElementById('kde-loading');
-    const plot = document.getElementById('dataset-kde-modalities');
-    if (loading && plot) {{
-        loading.style.display = 'none';
-        plot.style.display = 'block';
-        
-        // Add click event to points for navigation
-        plot.on('plotly_click', function(data) {{
-            if (data.points && data.points[0] && data.points[0].customdata) {{
-                const url = data.points[0].customdata[1]; // dataset_url
-                if (url) {{
-                    const resolved = new URL(url, window.location.href);
-                    window.open(resolved.href, '_self');
-                }}
-            }}
-        }});
+(function() {{
+  const TARGET_ID = 'dataset-kde-modalities';
+  const FIG_DATA = {data_json};
+  const FIG_LAYOUT = {layout_json};
+  const FIG_CONFIG = {config_json};
+
+  function onReady(callback) {{
+    if (document.readyState === 'loading') {{
+      document.addEventListener('DOMContentLoaded', callback, {{ once: true }});
+    }} else {{
+      callback();
     }}
-}});
+  }}
+
+  function renderPlot() {{
+    const container = document.getElementById(TARGET_ID);
+    if (!container) {{
+      return;
+    }}
+
+    const draw = () => {{
+      if (!window.Plotly) {{
+        window.requestAnimationFrame(draw);
+        return;
+      }}
+
+      window.Plotly.newPlot(TARGET_ID, FIG_DATA, FIG_LAYOUT, FIG_CONFIG).then((plot) => {{
+        const loading = document.getElementById('kde-loading');
+        if (loading) {{
+          loading.style.display = 'none';
+        }}
+        container.style.display = 'block';
+
+        plot.on('plotly_click', (event) => {{
+          const point = event.points && event.points[0];
+          if (!point || !point.customdata) {{
+            return;
+          }}
+          const url = point.customdata[1];
+          if (url) {{
+            const resolved = new URL(url, window.location.href);
+            window.open(resolved.href, '_self');
+          }}
+        }});
+      }});
+    }};
+
+    draw();
+  }}
+
+  onReady(renderPlot);
+}})();
 </script>
 """
 

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,65 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :member-order: bysource
+
+   {% block attributes %}
+   {%- if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block functions %}
+   {%- if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block classes %}
+   {%- if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block exceptions %}
+   {%- if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+{%- block modules %}
+{%- if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{%- endblock %}
+

docs/source/conf.py

@@ -293,6 +293,14 @@ def linkcode_resolve(domain, info):
 registered dynamically from mongo database. The table below summarises
 the distribution by experimental type as tracked in the summary file.
 
+Base Dataset API
+----------------
+
+.. toctree::
+   :maxdepth: 1
+
+   eegdash.dataset.EEGChallengeDataset
+
 .. list-table:: Dataset counts by experimental type
    :widths: 60 20
    :header-rows: 1
@@ -314,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
@@ -540,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/dataset_summary/bubble.rst

@@ -1,3 +1,5 @@
+.. rubric:: Dataset landscape
+
 .. raw:: html
 
    <figure class="eegdash-figure" style="margin: 0 0 1.25rem 0;">

docs/source/dataset_summary/kde.rst

@@ -1,3 +1,5 @@
+.. rubric:: Participant Distribution by Modality
+
 .. raw:: html
 
    <figure class="eegdash-figure" style="margin: 0 0 1.25rem 0;">