From 15dce604bcd505ac227f17f099d22ebc721a0e8e Mon Sep 17 00:00:00 2001
From: Antoine Guillaume <antoine.guillaume45@gmail.com>
Date: Thu, 18 Apr 2024 14:40:30 +0200
Subject: [PATCH] [DOC] Add estimator overview table with capabilities (#1426)

* Add estimator overview table with capabilities

* Fix typos

* remove unused css import and try markdown checkmarks

* Fix string backslash typo

* Try math rendering with p

* Add back JS script for table search

* Fix checkmarks (hopefuly)

* Add back field css and split columns for module

* Fix typos

* Add mathjax extension for math rendering

* Add mathjax extension for math rendering

* Try unicode char

* Raw unicode from file

* Try using datatable css/js for search and sort

* Fix table syntax

* Try DataTable by ID

* Try ID via md syntax

* ID on file generation

* Remove JS component and leave raw table without search

* Requested changes

* Typo
---
 docs/conf.py               | 89 +++++++++++++++++++++++++++++++++++++-
 docs/estimator_overview.md |  6 +++
 docs/index.md              |  1 +
 3 files changed, 94 insertions(+), 2 deletions(-)
 create mode 100644 docs/estimator_overview.md

diff --git a/docs/conf.py b/docs/conf.py
index a3bfd2f89a..6849d981ea 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -262,7 +262,9 @@ def find_source():
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-html_css_files = ["css/custom.css"]
+html_css_files = [
+    "css/custom.css",
+]
 
 html_show_sourcelink = False
 
@@ -288,7 +290,13 @@ def find_source():
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, "aeon.tex", "aeon Documentation", "aeon developers", "manual"),
+    (
+        master_doc,
+        "aeon.tex",
+        "aeon Documentation",
+        "aeon developers",
+        "manual",
+    ),
 ]
 
 # -- Options for manual page output ------------------------------------------
@@ -314,6 +322,83 @@ def find_source():
     ),
 ]
 
+
+def _make_estimator_overview(app):
+    """Make estimator overview table."""
+    import pandas as pd
+
+    from aeon.registry import all_estimators
+
+    def _does_not_start_with_underscore(input_string):
+        return not input_string.startswith("_")
+
+    # Columns for the output table
+    COLNAMES = ["Estimator name", "Module", "Method family"]
+    capabilities_to_include = [
+        "multivariate",
+        "unequal_length",
+        "missing_values",
+    ]
+
+    for capability_name in capabilities_to_include:
+        _str = capability_name.replace("_", " ")
+        COLNAMES.append(f"Supports {_str}")
+
+    data = {k: [] for k in COLNAMES}
+
+    for estimator_name, estimator_class in all_estimators():
+        algorithm_type = "::".join(str(estimator_class).split(".")[1:-2])
+        # fetch tags
+        tag_dict = estimator_class.get_class_tags()
+
+        # includes part of class string
+        modpath = str(estimator_class)[8:-2]
+        path_parts = modpath.split(".")
+        # joins strings excluding starting with '_'
+        clean_path = ".".join(list(filter(_does_not_start_with_underscore, path_parts)))
+        # adds html link reference
+        estimator_name_as_link = str(
+            '<a href="api_reference/auto_generated/'
+            + clean_path
+            + '.html">'
+            + estimator_name
+            + "</a>"
+        )
+        algorithm_type = algorithm_type.split("::")
+        data["Estimator name"].append(estimator_name_as_link)
+        data["Module"].append(algorithm_type[0])
+        if len(algorithm_type) > 1:
+            data["Method family"].append("/".join(algorithm_type[1:]))
+        else:
+            data["Method family"].append("N/A")
+        for capability_name in capabilities_to_include:
+            _val = tag_dict.get(f"capability:{capability_name}")
+            _str = capability_name.replace("_", " ")
+
+            # For case where tag is not included output as not supported.
+            if not _val or _val is None:
+                data[f"Supports {_str}"].append("\u274C")
+            else:
+                data[f"Supports {_str}"].append("\u2705")
+
+    df = pd.DataFrame.from_dict(data).sort_values(
+        by=["Module", "Method family", "Estimator name"]
+    )
+    df_str = df.to_markdown(index=False, tablefmt="github")
+    with open("estimator_overview_table.md", "w", encoding="utf-8") as file:
+        file.write(df_str)
+
+
+def setup(app):
+    """Set up sphinx builder.
+
+    Parameters
+    ----------
+    app : Sphinx application object
+    """
+    app.connect("builder-inited", _make_estimator_overview)
+
+
 # -- Extension configuration -------------------------------------------------
 
 # -- Options for nbsphinx extension ---------------------------------------
diff --git a/docs/estimator_overview.md b/docs/estimator_overview.md
new file mode 100644
index 0000000000..11a1c01a88
--- /dev/null
+++ b/docs/estimator_overview.md
@@ -0,0 +1,6 @@
+# Estimator Overview
+
+The table below gives an overview of all estimators in aeon and their capabilities.
+
+```{include} estimator_overview_table.md
+```
diff --git a/docs/index.md b/docs/index.md
index 026559effd..2827abd704 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -270,6 +270,7 @@ code_of_conduct.md
 :hidden:
 
 glossary.md
+estimator_overview.md
 changelog.md
 papers_using_aeon.md
 ```