From 793b2a0ab461d9baee38d16574b56fb21cfcd119 Mon Sep 17 00:00:00 2001
From: Nicolas Kruse <nicolas@nonan.net>
Date: Fri, 6 Jun 2025 09:04:42 +0200
Subject: [PATCH] doc build script and settings updated

---
 docs/source/conf.py                |  5 +--
 docs/source/generate_class_list.py | 58 ++++++++++++++++++++----------
 docs/source/index.md               |  9 +++--
 3 files changed, 46 insertions(+), 26 deletions(-)

diff --git a/docs/source/conf.py b/docs/source/conf.py
index 4187ecf..35ab3d2 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -17,7 +17,7 @@ author = 'Nicolas Kruse'
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints", "myst_parser"]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_autodoc_typehints", "myst_parser", "sphinx.ext.autosummary"]
 
 templates_path = ['_templates']
 exclude_patterns = []
@@ -26,7 +26,8 @@ exclude_patterns = []
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # html_theme = 'alabaster'
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 html_static_path = ['_static']
 
 autodoc_inherit_docstrings = True
+autoclass_content = 'both'
diff --git a/docs/source/generate_class_list.py b/docs/source/generate_class_list.py
index 8fa77cf..605b699 100644
--- a/docs/source/generate_class_list.py
+++ b/docs/source/generate_class_list.py
@@ -1,3 +1,5 @@
+# This script generates the source md-files for all classes and functions for the docs
+
 import importlib
 import inspect
 import fnmatch
@@ -16,21 +18,21 @@ def write_classes(f: TextIOWrapper, patterns: list[str], module_name: str, title
     ]
 
     """Write the classes to the file."""
-    f.write(f'## {title}\n\n')
     if description:
         f.write(f'{description}\n\n')
 
+    write_dochtree(f, title, classes)
+
     for cls in classes:
-        f.write('```{eval-rst}\n')
-        f.write(f'.. autoclass:: {module_name}.{cls}\n')
-        f.write('   :members:\n')
-        f.write('   :class-doc-from: both\n')
-        f.write('   :undoc-members:\n')
-        f.write('   :show-inheritance:\n')
-        f.write('   :inherited-members:\n')
-        if title != 'Base classes':
-            f.write('   :exclude-members: select\n')
-        f.write('```\n\n')
+        with open(f'docs/source/_autogenerated/{cls}.md', 'w') as f2:
+            f2.write(f'# {module_name}.{cls}\n')
+            f2.write('```{eval-rst}\n')
+            f2.write(f'.. autoclass:: {module_name}.{cls}\n')
+            f2.write('   :members:\n')
+            f2.write('   :undoc-members:\n')
+            f2.write('   :show-inheritance:\n')
+            f2.write('   :inherited-members:\n')
+            f2.write('```\n\n')
 
 
 def write_functions(f: TextIOWrapper, patterns: list[str], module_name: str, title: str, description: str = '', exclude: list[str] = []) -> None:
@@ -44,18 +46,36 @@ def write_functions(f: TextIOWrapper, patterns: list[str], module_name: str, tit
     ]
 
     """Write the classes to the file."""
-    f.write(f'## {title}\n\n')
     if description:
         f.write(f'{description}\n\n')
 
+    write_dochtree(f, title, functions)
+
     for func in functions:
         if not func.startswith('_'):
-            f.write('```{eval-rst}\n')
-            f.write(f'.. autofunction:: {module_name}.{func}\n')
-            f.write('```\n\n')
+            with open(f'docs/source/_autogenerated/{func}.md', 'w') as f2:
+                f2.write(f'# {module_name}.{func}\n')
+                f2.write('```{eval-rst}\n')
+                f2.write(f'.. autofunction:: {module_name}.{func}\n')
+                f2.write('```\n\n')
 
 
-with open('docs/source/modules.md', 'w') as f:
-    f.write('# Functions and classes\n\n')
-    write_classes(f, ['*'], 'gaspype', title='Classes')
-    write_functions(f, ['*'], 'gaspype', title='Functions')
+def write_dochtree(f: TextIOWrapper, title: str, items: list[str]):
+    f.write('```{toctree}\n')
+    f.write(':maxdepth: 1\n')
+    f.write(f':caption: {title}:\n')
+    #f.write(':hidden:\n')
+    for text in items:
+        if not text.startswith('_'):
+            f.write(f"{text}\n")
+    f.write('```\n\n')
+
+
+if __name__ == "__main__":
+    with open('docs/source/_autogenerated/index.md', 'w') as f:
+        f.write('# Classes and functions\n\n')
+        #f.write('## Classes\n\n')
+        write_classes(f, ['*'], 'gaspype', title='Classes')
+
+        #f.write('## Functions\n\n')
+        write_functions(f, ['*'], 'gaspype', title='Functions')
diff --git a/docs/source/index.md b/docs/source/index.md
index 7232e27..9e284ef 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -1,9 +1,8 @@
 ```{toctree}
-:maxdepth: 2
-:caption: Contents:
-
-readme
-modules
+:maxdepth: 1
+:hidden:
+_autogenerated/index
+_autogenerated/examples
 ```
 
 ```{include} ../../README.md