Skip to content

Commit 7a89d44

Browse files
MatrixEditorMatrixEditor
committed
Add documentation (API) for existing code base
--- + Add API reference for all implemented protocols + Add documentation for example scripts (mms_utility and mmsclient) + Fix various invalid documentation strings Workflows: + Documentation workflow now requires the package to be installed Examples: + mms_utility and mmsclient: Update parsing logic of targets and handle peer disconnects proto.cotp.connection: + Fix wrong logging message when sending TPDUs
1 parent 21f76f6 commit 7a89d44

42 files changed

Lines changed: 890 additions & 84 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci-docs.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,17 @@ jobs:
1515
uses: actions/setup-python@v5
1616
with:
1717
# Documentation uses the most stable Python version
18-
python-version: '3.12'
18+
python-version: '3.13'
1919

2020
- name: Install dependencies
2121
run: |
2222
python -m pip install --upgrade pip
2323
pip install -r docs/requirements-docs.txt
2424
25+
- name: Install Package
26+
run: |
27+
pip install -v .
28+
2529
- name: Build docs
2630
run: |
2731
cd docs

‎docs/source/_templates/repo-stats-custom.html‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{%- if source_type and source_user and source_repo and source_type in ("github", "gitlab") -%}
2+
3+
{%- if source_type == "github" -%}
4+
{%- set source_url = "https://github.com/{}/{}".format(source_user, source_repo) -%}
5+
{%- else -%}
6+
{%- set source_url = "https://gitlab.com/{}/{}".format(source_user, source_repo) -%}
7+
{%- endif -%}
8+
9+
<a class="js-repo-stats repo-stats flex items-center" href="{{ source_url }}"
10+
data-type="{{ source_type }}" data-user="{{ source_user }}" data-repo="{{ source_repo }}">
11+
<span class="w-8 flex items-center justify-around shrink-0 text-3xl">
12+
<iconify-icon icon="simple-icons:{{ source_type }}"></iconify-icon>
13+
</span>
14+
<span class="flex-grow px-2 break-all">
15+
<span style="font-size: small;">{{ source_user }}/{{ source_repo }}</span>
16+
<span class="flex text-sm repo-stats-count">
17+
<span class="flex items-center pr-3">
18+
<iconify-icon icon="lucide:star"></iconify-icon>
19+
<strong class="js-repo-stars ml-1">0</strong>
20+
</span>
21+
<span class="flex items-center">
22+
<iconify-icon icon="lucide:git-fork"></iconify-icon>
23+
<strong class="js-repo-forks ml-1">0</strong>
24+
</span>
25+
</span>
26+
</span>
27+
</a>
28+
{%- endif -%}

‎docs/source/conf.py‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@
1616

1717
# Next, we can import out module and all rypes on the struct classes will be
1818
# replaced by their runtime types
19-
sys.path.insert(0, str(PROJECT_ROOT / "src"))
19+
try:
20+
import icspacket
21+
except ImportError:
22+
sys.path.insert(0, str(PROJECT_ROOT / "src"))
2023

2124
# -- Project information -----------------------------------------------------
2225
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -40,7 +43,7 @@
4043

4144
templates_path = ["_templates"]
4245
exclude_patterns = []
43-
46+
autodoc_member_order = "bysource"
4447

4548
# -- Options for HTML output -------------------------------------------------
4649
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -49,3 +52,51 @@
4952

5053
html_copy_source = False
5154
html_show_sourcelink = False
55+
html_baseurl = "https://matrixeditor.github.io/icspacket/"
56+
57+
html_sidebars = {
58+
"**": [
59+
"sidebars/localtoc.html",
60+
"repo-stats-custom.html",
61+
"sidebars/edit-this-page.html",
62+
]
63+
}
64+
65+
html_context = {
66+
"source_type": "github",
67+
"source_user": "MatrixEditor",
68+
"source_repo": "icspacket",
69+
}
70+
71+
html_theme_options = {
72+
"accent_color": "lime",
73+
"color_mode": "dark",
74+
"github_url": "https://github.com/MatrixEditor/icspacket",
75+
"discussion_url": "https://github.com/MatrixEditor/icspacket/discussions",
76+
"globaltoc_expand_depth": 2,
77+
"nav_links": [
78+
{
79+
"title": "Examples",
80+
"url": "examples/index",
81+
"children": [
82+
{
83+
"title": "MMS Utilities",
84+
"url": "examples/mms/index",
85+
"summary": "Manufacturing Message Specification tools",
86+
"children": [
87+
{
88+
"title": "MMS Client",
89+
"url": "examples/mms/client",
90+
"summary": "Interactive MMS client shell",
91+
},
92+
{
93+
"title": "MMS Utility",
94+
"url": "examples/mms/utility",
95+
"summary": "Utility commands for MMS peers",
96+
},
97+
],
98+
},
99+
],
100+
},
101+
],
102+
}

‎docs/source/getting-started/coreapi.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.. _core_api:
2+
3+
4+
Core API Reference
5+
==================
6+
7+
.. automodule:: icspacket.core.connection
8+
:members:
9+
10+
.. automodule:: icspacket.core.logger
11+
:members:

‎docs/source/getting-started/installation.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _getting_started_install:
2+
3+
Installation
4+
============
5+
6+
7+
.. note::
8+
9+
For development, Python headers must be available.

‎docs/source/getting-started/protocols.rst‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
.. _getting_started_protocols:
2+
3+
Protocols Overview
4+
==================
5+
6+
7+
**Available protocols**
8+
9+
.. code-block::
10+
11+
tpkt
12+
cotp
13+
iso_ses
14+
iso_pres
15+
acse
16+
mms
17+
18+
19+
**Protocol references**
20+
21+
.. grid:: 1 1 2 3
22+
:gutter: 2
23+
:padding: 1
24+
:class-row: surface
25+
26+
.. grid-item-card:: :octicon:`plug` TPKT (RFC1006)
27+
:link: tpkt_index
28+
:link-type: ref
29+
30+
ISO Transport over TCP/IP.
31+
32+
.. grid-item-card:: :octicon:`link` COTP (X.224)
33+
:link: cotp_index
34+
:link-type: ref
35+
36+
Connection-Oriented Transport Protocol.
37+
38+
.. grid-item-card:: :octicon:`sign-in` COSP (X.225)
39+
:link: cosp_index
40+
:link-type: ref
41+
42+
Connection-Oriented Session Protocol.
43+
44+
.. grid-item-card:: :octicon:`browser` COPP (X.226)
45+
:link: copp_index
46+
:link-type: ref
47+
48+
Connection-Oriented Presentation Protocol.
49+
50+
51+
.. grid-item-card:: :octicon:`broadcast` ACSE (X.227)
52+
:link: acse_index
53+
:link-type: ref
54+
55+
Association Control Service Element.
56+
57+
58+
.. grid-item-card:: :octicon:`server` MMS (ISO 9506)
59+
:link: mms_index
60+
:link-type: ref
61+
62+
Manufacturing Message Specification protocol.
63+

‎docs/source/index.rst‎

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,82 @@
1-
.. _icspacket_index:
1+
.. :layout: compact
2+
3+
.. _icspacket_index:
4+
5+
icspacket
6+
=========
7+
8+
.. rst-class:: lead
9+
10+
*Contents of this side are WIP*
11+
12+
.. container:: buttons
13+
14+
`Getting Started <getting-started/installation.html>`_
15+
`Examples <examples/index.html>`_
16+
`GitHub <https://github.com/MatrixEditor/icspacket>`_
17+
18+
19+
20+
21+
22+
Getting Started
23+
---------------
24+
25+
Installation requires Python development headers, CMake, Ninja and a C compiler
26+
(preferrably GCC).
27+
28+
.. code-block:: bash
29+
30+
pip install git+https://github.com/MatrixEditor/icspacket
31+
32+
33+
.. toctree::
34+
:caption: Getting Started
35+
:hidden:
36+
37+
getting-started/installation
38+
getting-started/protocols
39+
getting-started/coreapi
40+
41+
.. toctree::
42+
:caption: MMS / ISO 9506
43+
:hidden:
44+
45+
protocols/mms/demo_vars
46+
protocols/mms/demo_files
47+
protocols/mms/api
48+
49+
50+
.. toctree::
51+
:caption: ACSE / X.227
52+
:hidden:
53+
54+
protocols/acse/api
55+
56+
.. toctree::
57+
:caption: COPP / X.226 / ISO 8823
58+
:hidden:
59+
60+
protocols/copp/api
61+
62+
63+
.. toctree::
64+
:caption: COSP / X.225 / ISO 8237-1
65+
:hidden:
66+
67+
protocols/cosp/api
68+
69+
70+
.. toctree::
71+
:caption: COTP / X.224
72+
:hidden:
73+
74+
protocols/cotp/api
75+
76+
77+
.. toctree::
78+
:caption: TPKT Protocol (RFC1006)
79+
:hidden:
80+
81+
protocols/tpkt/usage
82+
protocols/tpkt/api

‎docs/source/protocols/acse/api.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.. _acse_index:
2+
3+
API Reference
4+
=============
5+
6+
7+
.. automodule:: icspacket.proto.mms.acse
8+
:members: ACSEConnectionError, ACSEAuthenticationFailure, Authenticator, PasswordAuth, Association, build_release_request, build_abort_request, build_associate_request

‎docs/source/protocols/copp/api.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. _copp_index:
2+
3+
API Reference
4+
=============
5+
6+
.. toctree::
7+
:caption: Components
8+
9+
presentation
10+
utils

‎docs/source/protocols/copp/presentation.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _copp_presentation:
2+
3+
ISO Presentation
4+
================
5+
6+
.. automodule:: icspacket.proto.iso_pres.presentation
7+
:members:

0 commit comments

Comments
 (0)