Skip to content

Commit 484cf35

Browse files
a-alaka-alak
committed
Large rewritting of docs, first draft. Includes a restructuring of the docs setup, addition of multiple doc dependencies (sphinx_inline_tabs, myst_parser, sphinx_copybutton, furo theme), change of theme. Currently the biggest addition is tutorials. The API reference is mostly an AI created draft to get started. Includes suggestions on possible additions (how-to guides and topic guides).
1 parent ee2edcf commit 484cf35

39 files changed

+5057
-184
lines changed

‎docs/source/about/changelog.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Changelog
2+
=========
3+
4+
.. include:: ../../../CHANGELOG.md
5+
:parser: myst_parser.sphinx_

‎docs/source/about/contributing.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Contributing
2+
============
3+
4+
.. include:: ../../../CONTRIBUTING.md
5+
:parser: myst_parser.sphinx_

‎docs/source/about/index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
About
2+
=====
3+
4+
.. toctree::
5+
:maxdepth: 1
6+
7+
changelog
8+
contributing
9+
ressources

‎docs/source/about/ressources.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Ressources
2+
==========
3+
4+
... to be implemented ...

‎docs/source/api/charge_point.rst‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
ChargePoint
2+
===========
3+
4+
.. module:: ocpp.charge_point
5+
6+
The ChargePoint module provides the base class for implementing a Charge Point in OCPP.
7+
8+
ChargePoint
9+
-----------
10+
11+
.. autoclass:: ChargePoint
12+
:members:
13+
:undoc-members:
14+
:special-members: __init__
15+
16+
Core Methods
17+
~~~~~~~~~~~~
18+
19+
.. method:: ChargePoint.start()
20+
:async:
21+
22+
Start the main message processing loop.
23+
24+
This method enters an infinite loop to constantly receive and process incoming messages.
25+
26+
This is the main entry point that should be called after initializing a ChargePoint instance.
27+
28+
:return: This method doesn't return, it runs until the connection is closed.
29+
30+
.. method:: ChargePoint.route_message(raw_msg)
31+
:async:
32+
33+
Route a message received from a Central System.
34+
35+
If the message is a Call, the corresponding handler is executed.
36+
If the message is a CallResult or CallError, the message is passed to the call() function.
37+
38+
:param raw_msg: The raw message to route
39+
:type raw_msg: str
40+
:return: None
41+
42+
.. method:: ChargePoint.call(payload, suppress=True, unique_id=None, skip_schema_validation=False)
43+
:async:
44+
45+
Send a Call message to the Central System and return the response payload.
46+
47+
The given payload is transformed into a Call object by looking at the type.
48+
49+
:param payload: The payload to send (a call.* dataclass)
50+
:type payload: dataclass
51+
:param suppress: If True, CallErrors will be suppressed
52+
:type suppress: bool
53+
:param unique_id: Unique ID for the call, if not provided a UUID will be generated
54+
:type unique_id: str, optional
55+
:param skip_schema_validation: If True, schema validation will be skipped
56+
:type skip_schema_validation: bool
57+
:return: The response payload (a call_result.* dataclass)
58+
:raises asyncio.TimeoutError: If no response is received within the timeout
59+
:raises CallError: If suppress is False and a CallError is received
60+
61+
Utility Functions
62+
------------------
63+
64+
The ChargePoint module provides several utility functions that are used internally:
65+
66+
.. autofunction:: camel_to_snake_case
67+
.. autofunction:: snake_to_camel_case
68+
.. autofunction:: serialize_as_dict
69+
.. autofunction:: remove_nones

‎docs/source/api/exceptions.rst‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
Exceptions
2+
=========
3+
4+
.. module:: ocpp.exceptions
5+
6+
The exceptions module contains custom exceptions used by the OCPP library.
7+
8+
Base Exception
9+
-------------
10+
11+
.. exception:: OCPPError
12+
13+
Base class for all OCPP errors. This class should not be raised directly, only its subclasses.
14+
15+
:param description: Description of the error
16+
:type description: str, optional
17+
:param details: Additional details about the error
18+
:type details: dict, optional
19+
20+
.. attribute:: default_description
21+
:type: str
22+
23+
Default description used if no description is provided.
24+
25+
.. attribute:: code
26+
:type: str
27+
28+
The error code used in OCPP CallError messages. Defined in subclasses.
29+
30+
Protocol Error Exceptions
31+
-----------------------
32+
33+
.. exception:: NotImplementedError
34+
35+
Raised when a requested action is recognized but not supported by the receiver.
36+
37+
.. attribute:: code
38+
:type: str
39+
:value: "NotImplemented"
40+
41+
.. attribute:: default_description
42+
:type: str
43+
:value: "Request Action is recognized but not supported by the receiver"
44+
45+
.. exception:: NotSupportedError
46+
47+
Raised when a requested action is not known by the receiver.
48+
49+
.. attribute:: code
50+
:type: str
51+
:value: "NotSupported"
52+
53+
.. attribute:: default_description
54+
:type: str
55+
:value: "Requested Action is not known by receiver"
56+
57+
.. exception:: InternalError
58+
59+
Raised when an internal error occurred and the receiver was not able to process the request.
60+
61+
.. attribute:: code
62+
:type: str
63+
:value: "InternalError"
64+
65+
.. attribute:: default_description
66+
:type: str
67+
:value: "An internal error occurred and the receiver was not able to process the requested Action successfully"
68+
69+
.. exception:: ProtocolError
70+
71+
Raised when the payload for an action is incomplete.
72+
73+
.. attribute:: code
74+
:type: str
75+
:value: "ProtocolError"
76+
77+
.. attribute:: default_description
78+
:type: str
79+
:value: "Payload for Action is incomplete"
80+
81+
.. exception:: SecurityError
82+
83+
Raised when a security issue prevents the receiver from completing the action.
84+
85+
.. attribute:: code
86+
:type: str
87+
:value: "SecurityError"
88+
89+
.. attribute:: default_description
90+
:type: str
91+
:value: "During the processing of Action a security issue occurred preventing receiver from completing the Action successfully"
92+
93+
Format Violation Exceptions
94+
-------------------------
95+
96+
.. exception:: FormatViolationError
97+
98+
Raised when the payload for an action is syntactically incorrect.
99+
100+
.. attribute:: code
101+
:type: str
102+
:value: "FormatViolation"
103+
104+
.. attribute:: default_description
105+
:type: str
106+
:value: "Payload for Action is syntactically incorrect or structure for Action"
107+
108+
.. exception:: FormationViolationError
109+
110+
Used for strict OCPP 1.6 compliance (typo in the specification).
111+
112+
.. attribute:: code
113+
:type: str
114+
:value: "FormationViolation"
115+
116+
.. attribute:: default_description
117+
:type: str
118+
:value: "Payload for Action is syntactically incorrect or structure for Action"
119+
120+
Constraint Violation Exceptions
121+
-----------------------------
122+
123+
.. exception:: PropertyConstraintViolationError
124+
125+
Raised when a field contains an invalid value.
126+
127+
.. attribute:: code
128+
:type: str
129+
:value: "PropertyConstraintViolation"
130+
131+
.. attribute:: default_description
132+
:type: str
133+
:value: "Payload is syntactically correct but at least one field contains an invalid value"
134+
135+
.. exception:: OccurenceConstraintViolationError
136+
137+
Used for strict OCPP 1.6 compliance (typo in the specification).
138+
139+
.. attribute:: code
140+
:type: str
141+
:value: "OccurenceConstraintViolation"
142+
143+
.. attribute:: default_description
144+
:type: str
145+
:value: "Payload for Action is syntactically correct but at least one of the fields violates occurence constraints"
146+
147+
.. exception:: OccurrenceConstraintViolationError
148+
149+
Raised when a field violates occurrence constraints.
150+
151+
.. attribute:: code
152+
:type: str
153+
:value: "OccurrenceConstraintViolation"
154+
155+
.. attribute:: default_description
156+
:type: str
157+
:value: "Payload for Action is syntactically correct but at least one of the fields violates occurence constraints"
158+
159+
.. exception:: TypeConstraintViolationError
160+
161+
Raised when a field violates data type constraints.
162+
163+
.. attribute:: code
164+
:type: str
165+
:value: "TypeConstraintViolation"
166+
167+
.. attribute:: default_description
168+
:type: str
169+
:value: "Payload for Action is syntactically correct but at least one of the fields violates data type constraints (e.g. \"somestring\": 12)"
170+
171+
Other Exceptions
172+
--------------
173+
174+
.. exception:: GenericError
175+
176+
Generic error for all other types of errors.
177+
178+
.. attribute:: code
179+
:type: str
180+
:value: "GenericError"
181+
182+
.. attribute:: default_description
183+
:type: str
184+
:value: "Any other error not all other OCPP defined errors"
185+
186+
.. exception:: ValidationError
187+
188+
Raised when validation of a message payload fails. This is not an official OCPP error.
189+
190+
.. exception:: UnknownCallErrorCodeError
191+
192+
Raised when a CallError is received with an unknown error code.

‎docs/source/api/index.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
API Reference
2+
============
3+
4+
This section provides detailed documentation for the OCPP library's API.
5+
6+
The library is structured around several core components:
7+
8+
* **ChargePoint** - The main class that handles communication between the Charge Point and Central System
9+
* **Routing** - Decorators for routing incoming messages to handler methods
10+
* **Messages** - Classes and functions for handling OCPP messages
11+
* **Exceptions** - Custom exceptions for error handling
12+
* **OCPP Versions** - Version-specific implementations (1.6 and 2.0.1)
13+
14+
.. toctree::
15+
:maxdepth: 2
16+
17+
charge_point
18+
routing
19+
messages
20+
exceptions
21+
v16/index
22+
v201/index

0 commit comments

Comments
 (0)