docs: Googlestyle docstrings and initial help sections

doc/api_reference.rst

@@ -0,0 +1,89 @@
+API Reference
+=============
+
+Complete API documentation for the ChimeraTK DeviceAccess Python bindings.
+
+
+API Index
+~~~~~~~~~
+
+The entries below provide direct links to the most important module-level functions, classes, and enums.
+
+.. currentmodule:: deviceaccess
+
+.. autosummary::
+  :toctree: generated
+
+  setDMapFilePath
+  getDMapFilePath
+  Device
+  ScalarRegisterAccessor
+  OneDRegisterAccessor
+  TwoDRegisterAccessor
+  VoidRegisterAccessor
+  TransferGroup
+  ReadAnyGroup
+  DataConsistencyGroup
+  RegisterCatalogue
+  RegisterInfo
+  DataDescriptor
+  DataType
+  VersionNumber
+  AccessMode
+  DataValidity
+
+
+Core Classes
+~~~~~~~~~~~~
+
+**Device**
+  Main class for opening and managing connections to devices.
+
+**ScalarRegisterAccessor**
+  Accessor for single-valued registers.
+
+**OneDRegisterAccessor**
+  Accessor for array-valued registers.
+
+**TwoDRegisterAccessor**
+  Accessor for 2D array registers.
+
+
+Type Mapping
+~~~~~~~~~~~~
+
+Python types are automatically mapped to hardware types, Numpy types are also supported:
+
+* ``int`` ↔ int32
+* ``float`` ↔ float32
+* ``str`` ↔ String registers
+* ``list`` / ``array`` / ``numpy.ndarray`` ↔ Array registers
+
+
+Main Module: deviceaccess
+--------------------------
+
+.. automodule:: deviceaccess
+    :members:
+    :show-inheritance:
+
+
+Legacy Module: mtca4u
+---------------------
+
+.. note::
+
+   The ``mtca4u`` module is a legacy interface. New code should use the ``deviceaccess`` module instead.
+
+.. automodule:: mtca4u
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+See Also
+--------
+
+* :doc:`user_guide` for usage patterns and best practices
+* :doc:`examples` for practical code samples
+* :doc:`getting_started` for installation and basic usage
+* :doc:`faq` for common questions

doc/conf.py.in

@@ -22,8 +22,14 @@ import shlex
 sys.path.insert(0, os.path.abspath('${CMAKE_BINARY_DIR}'))
 
 #
-# Remove dependency of doc generation dependency from compilation.
-autodoc_mock_imports = ["_da_python_bindings"]
+# Mocking of the core C-extension breaks introspection (no members to document).
+# Only mock when the extension cannot be imported (e.g. on readthedocs),
+# otherwise use the built binary from CMAKE_BINARY_DIR so autodoc can see members.
+try:
+    import deviceaccess  # noqa: F401
+    autodoc_mock_imports = []
+except Exception:
+    autodoc_mock_imports = ["deviceaccess"]
 
 # -- General configuration ------------------------------------------------
 
@@ -35,11 +41,20 @@ autodoc_mock_imports = ["_da_python_bindings"]
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx_autodoc_typehints',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx',
 ]
 
+# Intersphinx mapping to link to external documentation
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 
@@ -112,12 +127,33 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+# -- Napoleon extension configuration (parse docstrings) ------------------
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_doc = True
+napoleon_include_private_with_doc = False
+napoleon_attr_annotations = True
+napoleon_preprocess_types = True
+
+# -- Autodoc configuration -------------------------------------------------
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': False,
+    'show-inheritance': True,
+}
+autodoc_typehints = 'short'
+autodoc_typehints_format = 'short'
+autosummary_generate = True
+autosummary_imported_members = False
+
 
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -126,7 +162,11 @@ html_theme_options = {
     'logo_name': 'true',
     'code_font_size': '.688em',
     'show_powered_by': 'false',
-    'github_button': 'false'}
+    'github_button': 'false',
+    'collapse_navigation': False,
+    'navigation_depth': 4,
+    'sticky_navigation': True,
+    'titles_only': False}
 # 'code_font_family': 'Deja Vu Sans Mono',}
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -150,7 +190,8 @@ html_sidebars = {
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = '${CMAKE_SOURCE_DIR}/doc/DESY_logo.png'
+html_logo = '${CMAKE_SOURCE_DIR}/doc/ChimeraTK_Logo_whitebg.png'
+html_favicon = '${CMAKE_SOURCE_DIR}/doc/ChimeraTK_Favicon.ico'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

doc/deviceaccess.rst

@@ -3,4 +3,5 @@ deviceaccess module
 
 .. automodule:: deviceaccess
     :members:
-    :show-inheritance:
+    :undoc-members:
+    :show-inheritance:

doc/examples.rst

@@ -0,0 +1,83 @@
+Examples
+========
+
+This page contains practical examples demonstrating common usage patterns with the DeviceAccess Python bindings.
+The actual example code, and the `map` and `dmap` files used in this example can be found in the `tests` folder of the source distribution. The content is also listed in the :ref:`Used Map Files section <used_map_files_section>` section below.
+
+.. _basic_example_python:
+
+Basic Scalar Register Access
+-----------------------------
+
+Reading and writing a single register value:
+
+.. literalinclude:: ../tests/testDocExamples.py
+   :pyobject: TestDocExamples.simpleScalarAccess
+   :lines: 2-
+   :dedent: 4
+
+
+.. _array_example_python:
+
+Working with 1D Accessors
+-------------------------
+
+Reading and processing array data:
+
+.. literalinclude:: ../tests/testDocExamples.py
+   :pyobject: TestDocExamples.simpleOneDAccess
+   :lines: 2-
+   :dedent: 4
+
+
+.. _device_map_example_python:
+
+Using Different Device Backends
+--------------------------------
+
+The ChimeraTK library supports multiple backends. Configure them in your device map file:
+
+.. code-block:: text
+
+   # Device map example
+    AMC_PCIe    (xdma:xdma/slot6?map=device.map)
+    SCPI_Dev    (CommandBasedTCP:lab_dev?map=hw_prep.json&port=50000)
+    OPCUADev    (opcua:192.168.1.101?port=16664)
+    DummyDev    (dummy?map=device.map)
+
+Then use them the same way in your Python code:
+
+.. code-block:: python
+
+   import deviceaccess
+
+   # Open different backend devices with same API
+   dummy = deviceaccess.Device("DummyDev")
+   pcie = deviceaccess.Device("AMC_PCIe")
+   scpi = deviceaccess.Device("SCPI_Dev")
+   opcua = deviceaccess.Device("OPCUADev")
+
+   # All use the same accessor interface
+   for device in [dummy, pcie, scpi, opcua]:
+       value = device.getScalarRegisterAccessor(int, "MEASUREMENT")
+       value.read()
+       print(f"Value: {float(value)}")
+
+.. _used_map_files_section:
+
+Used Map Files
+--------------
+
+.. literalinclude:: ../tests/documentationExamples/someCrate.dmap
+   :caption: Example Crate dMap File
+
+.. literalinclude:: ../tests/documentationExamples/someDummyModule.map
+   :caption: Example Module Map File
+
+
+See Also
+--------
+
+* :doc:`user_guide` for in-depth explanations
+* :doc:`api_reference` for complete API documentation
+* :doc:`faq` for common questions