.github/workflows/docs.yml

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

.gitignore

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

docs/source/conf.py

@@ -26,8 +26,7 @@ exclude_patterns = []
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # html_theme = 'alabaster'
-html_theme = 'pydata_sphinx_theme'
+html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
 autodoc_inherit_docstrings = True
-autoclass_content = 'both'

docs/source/generate_class_list.py

@@ -2,58 +2,42 @@ 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 if pat not in exclude) and
+            any(fnmatch.fnmatch(name, pat) for pat in patterns) and
-            (obj.__doc__ and ('(Automatic generated stub)' not in obj.__doc__ or ' digital ' in obj.__doc__)) and
+            obj.__doc__ and
-            obj.__doc__ and '(no I/O function)' not in obj.__doc__
+            # '(Automatic generated stub)' not in 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:
-        with open(f'docs/source/_autogenerated/{cls}.md', 'w') as f2:
+        if cls not in exclude:
-            f2.write(f'# {module_name}.{cls}\n')
+            f.write('```{eval-rst}\n')
-            f2.write('```{eval-rst}\n')
+            f.write(f'.. autoclass:: {module_name}.{cls}\n')
-            f2.write(f'.. autoclass:: {module_name}.{cls}\n')
+            f.write('   :members:\n')
-            f2.write('   :members:\n')
+            f.write('   :show-inheritance:\n')
-            f2.write('   :show-inheritance:\n')
+            f.write('   :inherited-members: object\n')
-            f2.write('   :inherited-members:\n')
             if title not in ['Base classes', 'Bus coupler']:
-                f2.write('   :exclude-members: select, parameters\n')
+                f.write('   :exclude-members: select, parameters\n')
-            f2.write('```\n\n')
+            else:
-
+                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')
 
 
-if __name__ == "__main__":
+with open('docs/source/modules.md', 'w') as f:
-    # 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,7 +1,9 @@
 ```{toctree}
-:maxdepth: 1
+:maxdepth: 2
-:hidden:
+:caption: Contents:
-_autogenerated/index
+
+readme
+modules
 ```
 
 ```{include} ../../README.md

docs/source/readme.md

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

pyproject.toml

@@ -29,12 +29,6 @@ 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 (list[BusTerminal]): A list of bus terminal classes according to the
+        bus_terminals: A list of bus terminal classes according to the
             connected terminals.
-        modbus (SimpleModbusClient): The underlying modbus client used for the connection.
+        modbus: 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,13 +48,20 @@ 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 (str): hostname or IP address
+        host: hostname or IP address
-        port (int): server port
+        port: server port
-        unit_id (int): ModBus id
+        unit_id: ModBus id
-        timeout (float): socket timeout in seconds
+        timeout: socket timeout in seconds
-        last_error (str): contains last error message or empty string if no error occurred
+        last_error: contains last error message or empty string if no error occurred
-        debug (bool): if True prints out transmitted and received bytes in hex
+        debug: if True prints out transmitted and received bytes in hex
 
     """