docs restructured and updated

.github/workflows/docs.yml

@@ -17,15 +17,13 @@ jobs:
         uses: actions/setup-python@v3
         with:
           python-version: "3.x"
-      - name: Install dependencies
+      - name: Install package and dependencies
-        run: pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints myst-parser
+        run: pip install .[doc_build]
       - name: Generate Class List
-        run: |
+        run: python ./docs/source/generate_class_list.py
-          pip install .
-          python ./docs/source/generate_class_list.py
       - name: Build Docs
         run: |
-          cp LICENSE docs/source/
+          cp LICENSE docs/source/LICENSE.md
           cd docs
           sphinx-apidoc -o ./source/ ../src/ -M --no-toc
           rm ./source/*.rst

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/_autogenerated/
 
 # Autogenerated documentation
 docs/source/modules.md

docs/source/conf.py

@@ -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'

docs/source/generate_class_list.py

@@ -2,42 +2,58 @@ import importlib
 import inspect
 import fnmatch
 from io import TextIOWrapper
+import os
 
 
 def write_classes(f: TextIOWrapper, patterns: list[str], module_name: str, title: str, description: str = '', exclude: list[str] = []) -> None:
-
+    """Write the classes to the file."""
     module = importlib.import_module(module_name)
 
     classes = [
         name for name, obj in inspect.getmembers(module, inspect.isclass)
         if (obj.__module__ == module_name and
-            any(fnmatch.fnmatch(name, pat) for pat in patterns) and
+            any(fnmatch.fnmatch(name, pat) for pat in patterns if pat not in exclude) and
-            obj.__doc__ and
+            (obj.__doc__ and ('(Automatic generated stub)' not in obj.__doc__ or ' digital ' in obj.__doc__)) and
-            # '(Automatic generated stub)' not in obj.__doc__ and
+            obj.__doc__ and '(no I/O function)' not in obj.__doc__
-            '(no I/O function)' not in obj.__doc__)
+            )
     ]
 
-    """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:
-        if cls not in exclude:
+        with open(f'docs/source/_autogenerated/{cls}.md', 'w') as f2:
-            f.write('```{eval-rst}\n')
+            f2.write(f'# {module_name}.{cls}\n')
-            f.write(f'.. autoclass:: {module_name}.{cls}\n')
+            f2.write('```{eval-rst}\n')
-            f.write('   :members:\n')
+            f2.write(f'.. autoclass:: {module_name}.{cls}\n')
-            f.write('   :show-inheritance:\n')
+            f2.write('   :members:\n')
-            f.write('   :inherited-members: object\n')
+            f2.write('   :show-inheritance:\n')
+            f2.write('   :inherited-members:\n')
             if title not in ['Base classes', 'Bus coupler']:
-                f.write('   :exclude-members: select, parameters\n')
+                f2.write('   :exclude-members: select, parameters\n')
-            else:
+            f2.write('```\n\n')
-                print('* ', cls)
+
+
+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')
 
 
-with open('docs/source/modules.md', 'w') as f:
+if __name__ == "__main__":
+    # Ensure the output directory exists
+    os.makedirs('docs/source/_autogenerated', exist_ok=True)
+
+    with open('docs/source/_autogenerated/index.md', 'w') as f:
         f.write('# Classes and Modules\n\n')
+
         write_classes(f, ['BK*', 'WAGO_750_352'], 'pyhoff.devices', title='Bus coupler',
                     description='These classes are bus couplers and are used to connect the IO bus terminals to a Ethernet interface.')
         write_classes(f, ['KL*'], 'pyhoff.devices', title='Beckhoff bus terminals')

docs/source/index.md

@@ -1,9 +1,7 @@
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
-:caption: Contents:
+:hidden:
-
+_autogenerated/index
-readme
-modules
 ```
 
 ```{include} ../../README.md

docs/source/readme.md

@@ -1,2 +0,0 @@
-```{include} ../../README.md
-```

pyproject.toml

@@ -29,6 +29,12 @@ where = ["src"]
 dev = [
     "pytest", "flake8", "mypy"
 ]
+doc_build = [
+  "sphinx",
+  "pydata_sphinx_theme",
+  "sphinx-autodoc-typehints",
+  "myst-parser"
+]
 
 [tool.mypy]
 files = ["src"]