Sequencial ci/cd and better readme

.github/workflows/ci.yml

@@ -6,19 +6,57 @@ on:
   pull_request:
 
 jobs:
-  test:
+  test-3_10:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest
+
+      - name: Run tests
+        run: pytest -q
+
+  test-3_11:
+    needs: test-3_10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pytest
+
+      - name: Run tests
+        run: pytest -q
 
+  test-3_12:
+    needs: test-3_11
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.12"
           cache: 'pip'
 
       - name: Install dependencies
@@ -28,5 +66,38 @@ jobs:
           pip install pytest
 
       - name: Run tests
+        run: pytest -q
+
+  docs:
+    needs: test-3_12
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install system dependencies
+        run: sudo apt-get install -y graphviz
+
+      - name: Install package + docs dependencies
+        run: pip install ".[docs]"
+
+      - name: Build Sphinx docs
         run: |
-          pytest -q
+          sphinx-build --keep-going -b html docs/ docs/_build/html 2>&1 | tee /tmp/sphinx_out.txt
+          # Fail if any WARNING line is present that is NOT the benign placeholder one
+          if grep -v "Unknown type: placeholder" /tmp/sphinx_out.txt | grep -q "^WARNING:"; then
+            echo "Unexpected Sphinx warnings found:"
+            grep -v "Unknown type: placeholder" /tmp/sphinx_out.txt | grep "^WARNING:"
+            exit 1
+          fi
+
+      - name: Upload HTML docs as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: html-docs
+          path: docs/_build/html/
+          retention-days: 7

dpg/__init__.py

@@ -5,6 +5,7 @@
     class_feature_predicate_counts,
     class_lookup_from_target_names,
     classwise_feature_bounds_from_communities,
+    export_dpg_html,
     plot_dpg,
     plot_dpg_class_bounds_vs_dataset_feature_ranges,
     plot_dpg_constraints_overview,
@@ -18,6 +19,7 @@
     "DecisionPredicateGraph",
     "DPGExplainer",
     "DPGExplanation",
+    "export_dpg_html",
     "plot_dpg",
     "plot_dpg_reg",
     "plot_dpg_constraints_overview",

dpg/explainer.py

@@ -144,6 +144,7 @@ def plot(
         pdf_dpi: int = 600,
         show: bool = True,
         export_pdf: bool = False,
+        export_html: bool = False,
     ) -> None:
         """Render a standard DPG plot."""
         if explanation is None:
@@ -165,6 +166,7 @@ def plot(
             pdf_dpi=pdf_dpi,
             show=show,
             export_pdf=export_pdf,
+            export_html=export_html,
         )
 
     def plot_communities(
@@ -182,6 +184,7 @@ def plot_communities(
         pdf_dpi: int = 600,
         show: bool = True,
         export_pdf: bool = False,
+        export_html: bool = False,
         community_threshold: float = 0.2,
     ) -> None:
         """Render a community-colored DPG plot."""
@@ -206,6 +209,7 @@ def plot_communities(
             pdf_dpi=pdf_dpi,
             show=show,
             export_pdf=export_pdf,
+            export_html=export_html,
         )
 
     def plot_lrc_importance(

dpg/sklearn_dpg.py

@@ -88,7 +88,8 @@ def test_dpg(datasets: str,
              clusters_flag: bool = False,
              threshold_clusters: Optional[float] = None,
              class_flag: bool = False,
-             seed:int = 160898) -> Optional[Tuple[Any, Any]]:
+             seed:int = 160898,
+             export_format: str = "svg") -> Optional[Tuple[Any, Any]]:
 
     """
     Unified function to train models and extract DPG for both standard and custom datasets.
@@ -193,7 +194,40 @@ def test_dpg(datasets: str,
             if '.' in datasets else datasets
         )
         plot_name +=  f"_{model_name}_l{n_learners}_pv{perc_var}_t{decimal_threshold}_{seed}"
-
+
+        # 1. Basic (plain) DPG
+        plot_dpg(
+            plot_name,
+            dot,
+            df,
+            df_edges,
+            save_dir=save_plot_dir,
+            class_flag=class_flag,
+            export_format=export_format,
+        )
+
+        # 2. One plot per node-metric attribute
+        node_attributes = [
+            "Degree",
+            "In degree nodes",
+            "Out degree nodes",
+            "Betweenness centrality",
+            "Local reaching centrality",
+        ]
+        for attr in node_attributes:
+            if attr in df.columns:
+                plot_dpg(
+                    plot_name,
+                    dot,
+                    df,
+                    df_edges,
+                    save_dir=save_plot_dir,
+                    attribute=attr,
+                    class_flag=class_flag,
+                    export_format=export_format,
+                )
+
+        # 3. Communities plot
         if communities:
             plot_dpg_communities(
                 plot_name,
@@ -203,18 +237,21 @@ def test_dpg(datasets: str,
                 save_dir=save_plot_dir,
                 class_flag=class_flag,
                 df_edges=df_edges,
+                export_format=export_format,
             )
-        else:
+
+        # 4. Clusters plot
+        if clusters is not None:
             plot_dpg(
                 plot_name,
                 dot,
                 df,
                 df_edges,
                 save_dir=save_plot_dir,
-                attribute=attribute,
                 clusters=clusters,
                 threshold_clusters=threshold_clusters,
                 class_flag=class_flag,
+                export_format=export_format,
             )
 
     return df, df_edges, df_dpg, clusters, node_prob, confidence