Automatically publish docs for the latest version to readthedocs

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Declare the Python requirements required to build your documentation
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/conf.py

@@ -17,6 +17,10 @@
 sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../'))
 
+# Mock dependencies to allow autodoc to work without external packages
+# This is needed because python-can requires sqlite3 which may not be available
+autodoc_mock_imports = ['can', 'can.typechecking', 'numpy']
+
 
 # -- Project information -----------------------------------------------------
 
@@ -41,8 +45,40 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',      # Support for Google/NumPy style docstrings
+    'sphinx.ext.viewcode',      # Add links to source code
+    'sphinx.ext.intersphinx',   # Link to other project's documentation
 ]
 
+# Autodoc configuration for comprehensive API documentation
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': True,
+    'show-inheritance': True,
+    'special-members': '__init__',
+    'inherited-members': True,
+    'member-order': 'bysource',
+}
+
+# Include both class docstring and __init__ docstring
+autoclass_content = 'both'
+
+# Napoleon settings for docstring parsing
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_type_aliases = None
+
+# Intersphinx mapping
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'can': ('https://python-can.readthedocs.io/en/stable/', None),
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/examples.rst

@@ -0,0 +1,81 @@
+Examples
+========
+
+This section contains example scripts demonstrating how to use the python-can-j1939 library.
+
+Basic Examples
+--------------
+
+Simple Receive Global
+~~~~~~~~~~~~~~~~~~~~~
+
+Receive J1939 messages globally on the CAN bus.
+
+.. literalinclude:: ../examples/simple_receive_global.py
+   :language: python
+   :caption: simple_receive_global.py
+
+Simple Receive Peer-to-Peer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Receive J1939 messages in peer-to-peer mode.
+
+.. literalinclude:: ../examples/simple_receive_peer_to_peer.py
+   :language: python
+   :caption: simple_receive_peer_to_peer.py
+
+Own CA Producer
+~~~~~~~~~~~~~~~
+
+Create a Controller Application (CA) that produces messages.
+
+.. literalinclude:: ../examples/own_ca_producer.py
+   :language: python
+   :caption: own_ca_producer.py
+
+Diagnostic Messages
+-------------------
+
+Example of using J1939 diagnostic messages (DM1, DM11, etc.).
+
+.. literalinclude:: ../examples/diagnostic_message.py
+   :language: python
+   :caption: diagnostic_message.py
+
+Transport Protocols (J1939-21 / J1939-22)
+-----------------------------------------
+
+J1939-22 Multi PG
+~~~~~~~~~~~~~~~~~
+
+Multi Parameter Group example using J1939-22 transport protocol.
+
+.. literalinclude:: ../examples/j1939_22_multi_pg.py
+   :language: python
+   :caption: j1939_22_multi_pg.py
+
+J1939-22 Transport Protocols
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Transport protocol example with J1939-22.
+
+.. literalinclude:: ../examples/j1939_22_transport_protocols.py
+   :language: python
+   :caption: j1939_22_transport_protocols.py
+
+J1939-21 CMDT Send/Receive
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Connection Mode Data Transfer examples.
+
+**Sender:**
+
+.. literalinclude:: ../examples/j1939_21_cmdt_send_receive/j1939_send.py
+   :language: python
+   :caption: j1939_send.py
+
+**Receiver:**
+
+.. literalinclude:: ../examples/j1939_21_cmdt_send_receive/j1939_receive.py
+   :language: python
+   :caption: j1939_receive.py

docs/index.rst

@@ -6,7 +6,9 @@ CAN SAE J1939 for Python
    :caption: Contents:
 
    readme
-
+   examples
+   source/j1939
+
 
 Indices and tables
 ==================

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=7.0
+sphinx_rtd_theme>=2.0
+python-can>=4.0

docs/source/j1939.rst

@@ -1,24 +1,85 @@
 j1939 package
 =============
 
+.. automodule:: j1939
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 Submodules
 ----------
 
+j1939.electronic\_control\_unit module
+--------------------------------------
+
+.. automodule:: j1939.electronic_control_unit
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+
 j1939.controller\_application module
 ------------------------------------
 
 .. automodule:: j1939.controller_application
     :members:
     :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
-j1939.electronic\_control\_unit module
---------------------------------------
+j1939.j1939\_21 module
+----------------------
 
-.. automodule:: j1939.electronic_control_unit
+.. automodule:: j1939.j1939_21
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+
+j1939.j1939\_22 module
+----------------------
+
+.. automodule:: j1939.j1939_22
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+
+j1939.Dm14Query module
+----------------------
+
+.. automodule:: j1939.Dm14Query
     :members:
     :undoc-members:
     :show-inheritance:
+    :special-members: __init__
+
+j1939.Dm14Server module
+-----------------------
+
+.. automodule:: j1939.Dm14Server
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+
+j1939.diagnostic\_messages module
+---------------------------------
+
+.. automodule:: j1939.diagnostic_messages
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+
+j1939.memory\_access module
+---------------------------
+
+.. automodule:: j1939.memory_access
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
 
 j1939.message\_id module
 ------------------------
@@ -27,6 +88,7 @@ j1939.message\_id module
     :members:
     :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 j1939.name module
 -----------------
@@ -35,6 +97,7 @@ j1939.name module
     :members:
     :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
 j1939.parameter\_group\_number module
 -------------------------------------
@@ -43,20 +106,21 @@ j1939.parameter\_group\_number module
     :members:
     :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
-j1939.version module
---------------------
+j1939.error\_info module
+------------------------
 
-.. automodule:: j1939.version
+.. automodule:: j1939.error_info
     :members:
     :undoc-members:
     :show-inheritance:
+    :special-members: __init__
 
+j1939.version module
+--------------------
 
-Module contents
----------------
-
-.. automodule:: j1939
+.. automodule:: j1939.version
     :members:
     :undoc-members:
     :show-inheritance:

j1939/electronic_control_unit.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import logging
 import can
 from can import Listener