diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..32f1a01 --- /dev/null +++ b/.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 diff --git a/docs/conf.py b/docs/conf.py index 8115e78..3e685a3 100644 --- a/docs/conf.py +++ b/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'] diff --git a/docs/examples.rst b/docs/examples.rst new file mode 100644 index 0000000..991f117 --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 9ea39ad..87ffea1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,9 @@ CAN SAE J1939 for Python :caption: Contents: readme - + examples + source/j1939 + Indices and tables ================== diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..ca4f303 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=7.0 +sphinx_rtd_theme>=2.0 +python-can>=4.0 diff --git a/docs/source/j1939.rst b/docs/source/j1939.rst index ef1dfd0..dcb4f66 100644 --- a/docs/source/j1939.rst +++ b/docs/source/j1939.rst @@ -1,9 +1,23 @@ 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 ------------------------------------ @@ -11,14 +25,61 @@ j1939.controller\_application module :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: diff --git a/j1939/electronic_control_unit.py b/j1939/electronic_control_unit.py index ef27f89..aca6b45 100644 --- a/j1939/electronic_control_unit.py +++ b/j1939/electronic_control_unit.py @@ -1,3 +1,5 @@ +from __future__ import annotations + import logging import can from can import Listener