docs: automatically create reference pages for the python library (#386)

Closes #385. ### Summary of Changes * Remove manually created API reference pages. * Instead add a script the automatically creates them, so changes to the API are immediately reflected in the documentation. --------- Co-authored-by: lars-reimann <[email protected]>
Safe-DS · Jan 27, 2023 · 641a966 · 641a966
1 parent 45e3d1f
commit 641a966
Show file tree

Hide file tree

Showing 54 changed files with 67 additions and 108 deletions.
diff --git a/docs/Stdlib/python/classification/AdaBoost.md b/docs/Stdlib/python/classification/AdaBoost.md
diff --git a/docs/Stdlib/python/classification/DecisionTree.md b/docs/Stdlib/python/classification/DecisionTree.md
diff --git a/docs/Stdlib/python/classification/GradientBoosting.md b/docs/Stdlib/python/classification/GradientBoosting.md
diff --git a/docs/Stdlib/python/classification/KNearestNeighbors.md b/docs/Stdlib/python/classification/KNearestNeighbors.md
diff --git a/docs/Stdlib/python/classification/LogisticRegression.md b/docs/Stdlib/python/classification/LogisticRegression.md
diff --git a/docs/Stdlib/python/classification/RandomForest.md b/docs/Stdlib/python/classification/RandomForest.md
diff --git a/docs/Stdlib/python/classification/metrics/accuracy.md b/docs/Stdlib/python/classification/metrics/accuracy.md
diff --git a/docs/Stdlib/python/data/BooleanColumnType.md b/docs/Stdlib/python/data/BooleanColumnType.md
diff --git a/docs/Stdlib/python/data/Column.md b/docs/Stdlib/python/data/Column.md
diff --git a/docs/Stdlib/python/data/ColumnStatistics.md b/docs/Stdlib/python/data/ColumnStatistics.md
diff --git a/docs/Stdlib/python/data/ColumnType.md b/docs/Stdlib/python/data/ColumnType.md
diff --git a/docs/Stdlib/python/data/FloatColumnType.md b/docs/Stdlib/python/data/FloatColumnType.md
diff --git a/docs/Stdlib/python/data/Imputer.md b/docs/Stdlib/python/data/Imputer.md
diff --git a/docs/Stdlib/python/data/IntColumnType.md b/docs/Stdlib/python/data/IntColumnType.md
diff --git a/docs/Stdlib/python/data/LabelEncoder.md b/docs/Stdlib/python/data/LabelEncoder.md
diff --git a/docs/Stdlib/python/data/OneHotEncoder.md b/docs/Stdlib/python/data/OneHotEncoder.md
diff --git a/docs/Stdlib/python/data/OptionalColumnType.md b/docs/Stdlib/python/data/OptionalColumnType.md
diff --git a/docs/Stdlib/python/data/OrdinalEncoder.md b/docs/Stdlib/python/data/OrdinalEncoder.md
diff --git a/docs/Stdlib/python/data/Row.md b/docs/Stdlib/python/data/Row.md
diff --git a/docs/Stdlib/python/data/StringColumnType.md b/docs/Stdlib/python/data/StringColumnType.md
diff --git a/docs/Stdlib/python/data/SupervisedDataset.md b/docs/Stdlib/python/data/SupervisedDataset.md
diff --git a/docs/Stdlib/python/data/Table.md b/docs/Stdlib/python/data/Table.md
diff --git a/docs/Stdlib/python/data/TableSchema.md b/docs/Stdlib/python/data/TableSchema.md
diff --git a/docs/Stdlib/python/exceptions/ColumnLengthMismatchError.md b/docs/Stdlib/python/exceptions/ColumnLengthMismatchError.md
diff --git a/docs/Stdlib/python/exceptions/ColumnSizeError.md b/docs/Stdlib/python/exceptions/ColumnSizeError.md
diff --git a/docs/Stdlib/python/exceptions/DuplicateColumnNameError.md b/docs/Stdlib/python/exceptions/DuplicateColumnNameError.md
diff --git a/docs/Stdlib/python/exceptions/IndexOutOfBoundsError.md b/docs/Stdlib/python/exceptions/IndexOutOfBoundsError.md
diff --git a/docs/Stdlib/python/exceptions/LearningError.md b/docs/Stdlib/python/exceptions/LearningError.md
diff --git a/docs/Stdlib/python/exceptions/MissingSchemaError.md b/docs/Stdlib/python/exceptions/MissingSchemaError.md
diff --git a/docs/Stdlib/python/exceptions/NonNumericColumnError.md b/docs/Stdlib/python/exceptions/NonNumericColumnError.md
diff --git a/docs/Stdlib/python/exceptions/NotFittedError.md b/docs/Stdlib/python/exceptions/NotFittedError.md
diff --git a/docs/Stdlib/python/exceptions/PredictionError.md b/docs/Stdlib/python/exceptions/PredictionError.md
diff --git a/docs/Stdlib/python/exceptions/SchemaMismatchError.md b/docs/Stdlib/python/exceptions/SchemaMismatchError.md
diff --git a/docs/Stdlib/python/exceptions/UnknownColumnNameError.md b/docs/Stdlib/python/exceptions/UnknownColumnNameError.md
diff --git a/docs/Stdlib/python/gen_ref_pages.py b/docs/Stdlib/python/gen_ref_pages.py
@@ -0,0 +1,53 @@
+# Inspired by https://mkdocstrings.github.io/recipes/#bind-pages-to-sections-themselves
+
+import sys
+from importlib import import_module
+from inspect import getmembers, isclass, isfunction
+from pathlib import Path
+
+import mkdocs_gen_files
+
+
+def list_class_and_function_names_in_module(module_name: str) -> list[str]:
+    """
+    Returns a list with the names of all classes and function names in the given module.
+    """
+
+    import_module(module_name)
+    module = sys.modules[module_name]
+
+    return [name for name, obj in getmembers(module) if isclass(obj) or isfunction(obj)]
+
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("Runtime/safe-ds").rglob("__init__.py")):
+    module_path = path.relative_to("Runtime/safe-ds").with_suffix("")
+    doc_path = path.relative_to("Runtime/safe-ds").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    # Skip demos, tests, etc.
+    parts = tuple(module_path.parts)
+    if parts[0] != "safe_ds":
+        continue
+
+    # Remove the final "__init__" part
+    parts = parts[:-1]
+
+    qualified_name = ".".join(parts)
+
+    for name in list_class_and_function_names_in_module(qualified_name):
+        doc_path = doc_path.with_name(f"{name}.md")
+        full_doc_path = full_doc_path.with_name(f"{name}.md")
+
+        nav[parts + (name,)] = doc_path.as_posix()
+
+        # Create one file containing the documentation for the current class or function
+        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+            ident = qualified_name + "." + name
+            fd.write(f"::: {ident}")
+
+        mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
diff --git a/docs/Stdlib/python/plotting/plot_boxplot.md b/docs/Stdlib/python/plotting/plot_boxplot.md
diff --git a/docs/Stdlib/python/plotting/plot_correlation_heatmap.md b/docs/Stdlib/python/plotting/plot_correlation_heatmap.md
diff --git a/docs/Stdlib/python/plotting/plot_histogram.md b/docs/Stdlib/python/plotting/plot_histogram.md
diff --git a/docs/Stdlib/python/plotting/plot_lineplot.md b/docs/Stdlib/python/plotting/plot_lineplot.md
diff --git a/docs/Stdlib/python/plotting/plot_scatterplot.md b/docs/Stdlib/python/plotting/plot_scatterplot.md
diff --git a/docs/Stdlib/python/regression/AdaBoost.md b/docs/Stdlib/python/regression/AdaBoost.md
diff --git a/docs/Stdlib/python/regression/DecisionTree.md b/docs/Stdlib/python/regression/DecisionTree.md
diff --git a/docs/Stdlib/python/regression/ElasticNetRegression.md b/docs/Stdlib/python/regression/ElasticNetRegression.md
diff --git a/docs/Stdlib/python/regression/GradientBoosting.md b/docs/Stdlib/python/regression/GradientBoosting.md
diff --git a/docs/Stdlib/python/regression/KNearestNeighbors.md b/docs/Stdlib/python/regression/KNearestNeighbors.md
diff --git a/docs/Stdlib/python/regression/LassoRegression.md b/docs/Stdlib/python/regression/LassoRegression.md
diff --git a/docs/Stdlib/python/regression/LinearRegression.md b/docs/Stdlib/python/regression/LinearRegression.md
diff --git a/docs/Stdlib/python/regression/RandomForest.md b/docs/Stdlib/python/regression/RandomForest.md
diff --git a/docs/Stdlib/python/regression/RidgeRegression.md b/docs/Stdlib/python/regression/RidgeRegression.md
diff --git a/docs/Stdlib/python/regression/metrics/mean_absolute_error.md b/docs/Stdlib/python/regression/metrics/mean_absolute_error.md
diff --git a/docs/Stdlib/python/regression/metrics/mean_squared_error.md b/docs/Stdlib/python/regression/metrics/mean_squared_error.md
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,4 +2,7 @@ mkdocs==1.4.2
 mkdocstrings==0.20.0
 mkdocstrings-python==0.8.3
 mkdocs-autorefs==0.4.1
+mkdocs-gen-files==0.4.0
+mkdocs-literate-nav==0.6.0
 mkdocs-material==9.0.6
+mkdocs-section-index==0.3.4
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -8,64 +8,8 @@ nav:
       - Language: DSL/README.md
       - Standard Library: Stdlib/API/README.md
   - Python Library:
-      - Classification:
-          - Metrics:
-              - Stdlib/python/classification/metrics/accuracy.md
-          - Stdlib/python/classification/AdaBoost.md
-          - Stdlib/python/classification/DecisionTree.md
-          - Stdlib/python/classification/GradientBoosting.md
-          - Stdlib/python/classification/KNearestNeighbors.md
-          - Stdlib/python/classification/LogisticRegression.md
-          - Stdlib/python/classification/RandomForest.md
-      - Data:
-          - Stdlib/python/data/BooleanColumnType.md
-          - Stdlib/python/data/Column.md
-          - Stdlib/python/data/ColumnStatistics.md
-          - Stdlib/python/data/ColumnType.md
-          - Stdlib/python/data/FloatColumnType.md
-          - Stdlib/python/data/Imputer.md
-          - Stdlib/python/data/IntColumnType.md
-          - Stdlib/python/data/LabelEncoder.md
-          - Stdlib/python/data/OneHotEncoder.md
-          - Stdlib/python/data/OptionalColumnType.md
-          - Stdlib/python/data/OrdinalEncoder.md
-          - Stdlib/python/data/Row.md
-          - Stdlib/python/data/StringColumnType.md
-          - Stdlib/python/data/SupervisedDataset.md
-          - Stdlib/python/data/Table.md
-          - Stdlib/python/data/TableSchema.md
-      - Exceptions:
-          - Stdlib/python/exceptions/ColumnLengthMismatchError.md
-          - Stdlib/python/exceptions/ColumnSizeError.md
-          - Stdlib/python/exceptions/DuplicateColumnNameError.md
-          - Stdlib/python/exceptions/IndexOutOfBoundsError.md
-          - Stdlib/python/exceptions/LearningError.md
-          - Stdlib/python/exceptions/MissingSchemaError.md
-          - Stdlib/python/exceptions/NonNumericColumnError.md
-          - Stdlib/python/exceptions/NotFittedError.md
-          - Stdlib/python/exceptions/PredictionError.md
-          - Stdlib/python/exceptions/SchemaMismatchError.md
-          - Stdlib/python/exceptions/UnknownColumnNameError.md
-      - Plotting:
-          - Stdlib/python/plotting/plot_boxplot.md
-          - Stdlib/python/plotting/plot_correlation_heatmap.md
-          - Stdlib/python/plotting/plot_histogram.md
-          - Stdlib/python/plotting/plot_lineplot.md
-          - Stdlib/python/plotting/plot_scatterplot.md
-      - Regression:
-          - Metrics:
-              - Stdlib/python/regression/metrics/mean_absolute_error.md
-              - Stdlib/python/regression/metrics/mean_squared_error.md
-          - Stdlib/python/regression/AdaBoost.md
-          - Stdlib/python/regression/DecisionTree.md
-          - Stdlib/python/regression/ElasticNetRegression.md
-          - Stdlib/python/regression/GradientBoosting.md
-          - Stdlib/python/regression/KNearestNeighbors.md
-          - Stdlib/python/regression/LassoRegression.md
-          - Stdlib/python/regression/LinearRegression.md
-          - Stdlib/python/regression/RandomForest.md
-          - Stdlib/python/regression/RidgeRegression.md
-      - Stdlib/python/Tutorials/README.md
+      - API Reference: reference/
+      - Tutorials: Stdlib/python/Tutorials/README.md
   - Developer Guide: Development/README.md
 
 # Configuration of MkDocs & Material for MkDocs --------------------------------
@@ -90,6 +34,7 @@ theme:
       accent: orange
   features:
     - content.code.copy
+    - navigation.tabs
     - navigation.instant
     - navigation.sections
 
@@ -102,6 +47,12 @@ plugins:
           options:
             docstring_style: numpy
             show_if_no_docstring: true
+  - gen-files:
+      scripts:
+        - docs/Stdlib/python/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
   - autorefs
   - search
 

diff --git a/readthedocs.yml b/readthedocs.yml
@@ -11,3 +11,5 @@ mkdocs:
 python:
   install:
     - requirements: docs/requirements.txt
+    - method: pip
+      path: Runtime/safe-ds