Merge branch 'main' of https://github.com/Nonannet/pyhoff

.github/workflows/docs.yml

@@ -17,15 +17,13 @@ jobs:
         uses: actions/setup-python@v3
         with:
           python-version: "3.x"
-      - name: Install dependencies
-        run: pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints myst-parser
+      - name: Install package and dependencies
+        run: pip install .[doc_build]
       - name: Generate Class List
-        run: |
-          pip install .
-          python ./docs/source/generate_class_list.py
+        run: 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,48 +2,64 @@ 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
-            obj.__doc__ and
-            # '(Automatic generated stub)' not in obj.__doc__ and
-            '(no I/O function)' not in obj.__doc__)
+            any(fnmatch.fnmatch(name, pat) for pat in patterns if pat not in exclude) and
+            (obj.__doc__ and ('(Automatic generated stub)' not in obj.__doc__ or ' digital ' in obj.__doc__)) and
+            obj.__doc__ and '(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:
-            f.write('```{eval-rst}\n')
-            f.write(f'.. autoclass:: {module_name}.{cls}\n')
-            f.write('   :members:\n')
-            f.write('   :show-inheritance:\n')
-            f.write('   :inherited-members: object\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('   :show-inheritance:\n')
+            f2.write('   :inherited-members:\n')
             if title not in ['Base classes', 'Bus coupler']:
-                f.write('   :exclude-members: select, parameters\n')
-            else:
-                print('* ', cls)
-            f.write('```\n\n')
+                f2.write('   :exclude-members: select, parameters\n')
+            f2.write('```\n\n')
 
 
-with open('docs/source/modules.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')
-    write_classes(f, ['WAGO*'], 'pyhoff.devices', title='WAGO bus terminals', exclude=['WAGO_750_352'])
-    write_classes(f, ['*Terminal*'], 'pyhoff.devices', title='Generic bus terminals')
-    write_classes(f, ['*'], 'pyhoff', title='Base classes',
-                  description='These classes are base classes for devices and are typically not used directly.')
-    write_classes(f, ['*'], 'pyhoff.modbus', title='Modbus',
-                  description='This modbus implementation is used internally.')
+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__":
+    # 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')
+        write_classes(f, ['WAGO*'], 'pyhoff.devices', title='WAGO bus terminals', exclude=['WAGO_750_352'])
+        write_classes(f, ['*Terminal*'], 'pyhoff.devices', title='Generic bus terminals')
+        write_classes(f, ['*'], 'pyhoff', title='Base classes',
+                      description='These classes are base classes for devices and are typically not used directly.')
+        write_classes(f, ['*'], 'pyhoff.modbus', title='Modbus',
+                      description='This modbus implementation is used internally.')

docs/source/index.md

@@ -1,9 +1,7 @@
 ```{toctree}
-:maxdepth: 2
-:caption: Contents:
-
-readme
-modules
+:maxdepth: 1
+:hidden:
+_autogenerated/index
 ```
 
 ```{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"]

src/pyhoff/__init__.py

@@ -226,9 +226,9 @@ class BusCoupler():
     Base class for ModBus TCP bus coupler
 
     Attributes:
-        bus_terminals: A list of bus terminal classes according to the
+        bus_terminals (list[BusTerminal]): A list of bus terminal classes according to the
             connected terminals.
-        modbus: The underlying modbus client used for the connection.
+        modbus (SimpleModbusClient): The underlying modbus client used for the connection.
     """
 
     def __init__(self, host: str, port: int = 502, bus_terminals: Iterable[type[BusTerminal]] = [],

src/pyhoff/modbus.py

@@ -48,20 +48,13 @@ class SimpleModbusClient:
     """
     A simple Modbus TCP client
 
-    Args:
-        host: hostname or IP address
-        port: server port
-        unit_id: ModBus id
-        timeout: socket timeout in seconds
-        debug: if True prints out transmitted and received bytes in hex
-
     Attributes:
-        host: hostname or IP address
-        port: server port
-        unit_id: ModBus id
-        timeout: socket timeout in seconds
-        last_error: contains last error message or empty string if no error occurred
-        debug: if True prints out transmitted and received bytes in hex
+        host (str): hostname or IP address
+        port (int): server port
+        unit_id (int): ModBus id
+        timeout (float): socket timeout in seconds
+        last_error (str): contains last error message or empty string if no error occurred
+        debug (bool): if True prints out transmitted and received bytes in hex
 
     """