Skip to content

Commit f47cdb8

Browse files
ptrstnptrstn
committed
Create docs with Material for MkDocs
1 parent be90338 commit f47cdb8

File tree

14 files changed

+823
-108
lines changed

14 files changed

+823
-108
lines changed

‎README.md‎

Lines changed: 69 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
1-
<p align="center">
2-
<img src="docs/logo.svg" alt="shellsmith" width="50%">
3-
</p>
1+
<div align="center">
2+
<img src="docs/images/logo-purple.png" alt="shellsmith" style="max-width: 100%; width: 600px;">
3+
</div>
44

5-
<p align="center">
5+
<div align="center">
66
<a href="https://github.com/ptrstn/shellsmith/actions/workflows/test.yaml"><img src="https://github.com/ptrstn/shellsmith/actions/workflows/test.yaml/badge.svg" alt="Test"></a>
77
<a href="https://codecov.io/gh/ptrstn/shellsmith"><img src="https://codecov.io/gh/ptrstn/shellsmith/branch/main/graph/badge.svg" alt="codecov"></a>
88
<a href="https://pypi.org/project/shellsmith"><img src="https://img.shields.io/pypi/v/shellsmith?color=%2334D058" alt="PyPI - Version"></a>
99
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
10+
</div>
11+
12+
<p align="center">
13+
<b>Documentation</b>: <a href="https://shellsmith.pages.dev/" target="_blank">https://shellsmith.pages.dev</a>
1014
</p>
1115

1216
**Shellsmith** is a Python SDK and CLI for managing [Asset Administration Shells (AAS)](https://industrialdigitaltwin.org/en/content-hub/aasspecifications), Submodels, and Submodel Elements via the [Eclipse BaSyx](https://www.eclipse.org/basyx/) REST API.
@@ -15,10 +19,10 @@ It provides full client-side access to AAS resources with a clean Python interfa
1519

1620
### Features
1721

18-
- 🔧 **Python SDK** for full CRUD access to Shells, Submodels, and Submodel Elements
22+
- 🐍 **Python SDK** for full CRUD access to Shells, Submodels, and Submodel Elements
1923
- ⚡ **CLI tool** powered by [Typer](https://typer.tiangolo.com/) for fast scripting and automation
2024
- ⚙️ Simple `.env`-based configuration for flexible environment switching
21-
- 🔁 Seamless integration with the [Eclipse BaSyx](https://www.eclipse.org/basyx/) AAS REST API
25+
- 🔁 Seamless integration with the [Eclipse BaSyx](https://www.eclipse.org/basyx/) Environment REST API
2226

2327
## 🚀 Installation
2428

@@ -52,8 +56,8 @@ aas --help
5256

5357
| Command | Description |
5458
|----------|----------------------------------------------------------|
55-
| `upload` | Upload a single AAS file or all AAS files from a folder. |
5659
| `info` | Display the current Shell tree and identify issues. |
60+
| `upload` | Upload a single AAS file or all AAS files from a folder. |
5761
| `nuke` | ☢️ Delete all Shells and Submodels (irrevocable). |
5862
| `encode` | Encode a value (e.g. Shell ID) to Base64. |
5963
| `decode` | Decode a Base64-encoded value. |
@@ -66,52 +70,55 @@ aas --help
6670
6771
### 🔎 Get Commands
6872

69-
| Command | Description |
70-
|-------------------------------------------------|---------------------------------------------|
71-
| `aas get shells` | 🔹 Get all available Shells. |
72-
| `aas get shell <id>` | 🔹 Get a specific Shell by ID. |
73-
| `aas get submodel-refs <shell-id>` | 🔹 Get all Submodel References of a Shell. |
74-
| `aas get submodels` | 🔸 Get all Submodels. |
75-
| `aas get submodel <id>` | 🔸 Get a specific Submodel by ID. |
76-
| `aas get submodel-value <id>` | 🔸 Get the `$value` of a Submodel. |
77-
| `aas get submodel-meta <id>` | 🔸 Get the `$metadata` of a Submodel. |
78-
| `aas get elements <submodel-id>` | 🔻 Get all Submodel Elements of a Submodel. |
79-
| `aas get element <submodel-id> <idShort>` | 🔻 Get a specific Submodel Element. |
80-
| `aas get element-value <submodel-id> <idShort>` | 🔻 Get the `$value` of a Submodel Element. |
73+
| Command | Description |
74+
|---------------------------|---------------------------------------------|
75+
| `aas get shells` | 🔹 Get all available Shells. |
76+
| `aas get shell` | 🔹 Get a specific Shell by ID. |
77+
| `aas get submodel-refs` | 🔹 Get all Submodel References of a Shell. |
78+
| `aas get submodels` | 🔸 Get all Submodels. |
79+
| `aas get submodel ` | 🔸 Get a specific Submodel by ID. |
80+
| `aas get submodel-value ` | 🔸 Get the `$value` of a Submodel. |
81+
| `aas get submodel-meta` | 🔸 Get the `$metadata` of a Submodel. |
82+
| `aas get elements` | 🔻 Get all Submodel Elements of a Submodel. |
83+
| `aas get element` | 🔻 Get a specific Submodel Element. |
84+
| `aas get element-value` | 🔻 Get the `$value` of a Submodel Element. |
8185

8286
### 🛠️ Create Commands
8387

84-
| Command | Description |
85-
|------------------------------------------------------------------------------|-----------------------------------------|
86-
| `aas create shell [--data <json>] [--file <path>]` | 🔹 Create a new Shell. |
87-
| `aas create submodel-ref <shell-id> [--data <json>] [--file <path>]` | 🔹 Add a Submodel Reference to a Shell. |
88-
| `aas create submodel [--data <json>] [--file <path>]` | 🔸 Create a new Submodel. |
89-
| `aas create element <submodel-id> [--data <json>] [--file <path>]` | 🔻 Create a new Submodel Element. |
90-
| `aas create element <submodel-id> <idShort> [--data <json>] [--file <path>]` | 🔻 Create an Element at a nested path. |
88+
| Command | Description |
89+
|----------------------------|-----------------------------------------|
90+
| `aas create shell ` | 🔹 Create a new Shell. |
91+
| `aas create submodel-ref ` | 🔹 Add a Submodel Reference to a Shell. |
92+
| `aas create submodel` | 🔸 Create a new Submodel. |
93+
| `aas create element ` | 🔻 Create a new Submodel Element. |
94+
| `aas create element` | 🔻 Create an Element at a nested path. |
9195

9296
> ℹ️ Input can be passed via `--data "<json>"` or `--file <*.json|*.yaml>`, but **not both**
9397
9498
### 🧬 Update Commands
9599

96-
| Command | Description |
97-
|------------------------------------------------------------------------------|----------------------------------------------------------------|
98-
| `aas update shell <id> [--data <json>] [--file <path>]` | 🔹 Update a Shell (full replacement). |
99-
| `aas update submodel <id> [--data <json>] [--file <path>]` | 🔸 Update a Submodel (full replacement). |
100-
| `aas update submodel-value <id> [--data <json>] [--file <path>]` | 🔸 Update the `$value` of a Submodel (partial update). |
101-
| `aas update element <submodel-id> <idShort> [--data <json>] [--file <path>]` | 🔻 Update a Submodel Element (full replacement). |
102-
| `aas update element-value <submodel-id> <idShort> <value>` | 🔻 Update the `$value` of a Submodel Element (partial update). |
100+
| Command | Description |
101+
|------------------------------|----------------------------------------------------------------|
102+
| `aas update shell ` | 🔹 Update a Shell (full replacement). |
103+
| `aas update submodel` | 🔸 Update a Submodel (full replacement). |
104+
| `aas update submodel-value ` | 🔸 Update the `$value` of a Submodel (partial update). |
105+
| `aas update element ` | 🔻 Update a Submodel Element (full replacement). |
106+
| `aas update element-value ` | 🔻 Update the `$value` of a Submodel Element (partial update). |
103107

104108
> ℹ️ All updates are either full replacements (`PUT`) or partial updates (`PATCH`)
105109
106110
### 🧹 Delete Commands
107111

108-
| Command | Description |
109-
|----------------------------------------------------|----------------------------------------------------------------|
110-
| `aas delete shell <id> [--cascade]` | 🔹 Delete a Shell and optionally all referenced Submodels. |
111-
| `aas delete submodel-ref <shell-id> <submodel-id>` | 🔹 Remove a Submodel reference from a Shell. |
112-
| `aas delete submodel <id> [--remove-refs]` | 🔸 Delete a Submodel and optionally unlink it from all Shells. |
113-
| `aas delete element <submodel-id> <idShort>` | 🔻 Delete a Submodel Element. |
112+
| Command | Description |
113+
|---------------------------|----------------------------------------------------------------|
114+
| `aas delete shell` | 🔹 Delete a Shell and optionally all referenced Submodels. |
115+
| `aas delete submodel-ref` | 🔹 Remove a Submodel reference from a Shell. |
116+
| `aas delete submodel` | 🔸 Delete a Submodel and optionally unlink it from all Shells. |
117+
| `aas delete element` | 🔻 Delete a Submodel Element. |
118+
119+
> ℹ️ You can pass `--cascade` to also remove the Submodels the Shell references
114120
121+
> ℹ️ You can pass `--remove-refs` to also remove all references to that Submodel
115122
116123
## 🐍 Python API Usage
117124

@@ -124,11 +131,11 @@ import shellsmith
124131
shells = shellsmith.get_shells()
125132

126133
# Fetch a specific Shell by ID
127-
shell = shellsmith.get_shell("https://example.com/aas/my-asset")
134+
shell = shellsmith.get_shell("https://example.com/shells/my-shell")
128135

129136
# List Submodels or Submodel References of a Shell
130137
submodels = shellsmith.get_submodels()
131-
refs = shellsmith.get_submodel_refs("https://example.com/aas/my-asset")
138+
refs = shellsmith.get_submodel_refs("https://example.com/shells/my-shell")
132139

133140
# Fetch a specific Submodel
134141
submodel = shellsmith.get_submodel("https://example.com/submodels/my-submodel")
@@ -201,6 +208,8 @@ The tables below show the mapping between BaSyx AAS REST API endpoints and the i
201208
202209
## ⚙️ Development
203210

211+
Clone the repository and set up the virtual environment:
212+
204213
```bash
205214
git clone https://github.com/ptrstn/shellsmith
206215
cd shellsmith
@@ -211,19 +220,19 @@ pip install -e .[test]
211220

212221
### ✅ Testing
213222

214-
Before running the tests, make sure the BaSyx stack is up and running:
223+
Start the BaSyx stack (if needed):
215224

216225
```bash
217226
docker compose up -d
218227
```
219228

220-
Then run the test suite with coverage:
229+
Run the test suite with coverage:
221230

222231
```bash
223232
pytest --cov
224233
```
225234

226-
To view a detailed, visual coverage report:
235+
Generate an HTML coverage report:
227236

228237
```bash
229238
pytest --cov --cov-report=html
@@ -253,6 +262,22 @@ Format code:
253262
ruff format
254263
```
255264

265+
### 📚 Documentation
266+
267+
Serve the docs locally:
268+
269+
```bash
270+
mkdocs serve
271+
```
272+
273+
Then visit [http://127.0.0.1:8000](http://127.0.0.1:8000) to preview.
274+
275+
Build the static site:
276+
277+
```bash
278+
mkdocs build
279+
```
280+
256281
## Resources
257282

258283
- https://github.com/eclipse-basyx/basyx-java-server-sdk

‎docs/api.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# 🐍 Python API
2+
3+
Shellsmith provides a Python SDK to interact with the [Eclipse BaSyx](https://www.eclipse.org/basyx/) AAS REST API.
4+
5+
---
6+
7+
## 🚀 Quick Start
8+
9+
```python
10+
import shellsmith
11+
12+
# Get all Shells
13+
shells = shellsmith.get_shells()
14+
15+
# Fetch a specific Shell by ID
16+
shell = shellsmith.get_shell("https://example.com/submodels/my-submodel")
17+
18+
# Fetch a specific Submodel by ID
19+
submodel = shellsmith.get_submodel("https://example.com/submodels/my-submodel")
20+
21+
# Read and update a Submodel Element's value
22+
value = shellsmith.get_submodel_element_value(submodel["id"], "temperature")
23+
shellsmith.patch_submodel_element_value(submodel["id"], "temperature", "42.0")
24+
```
25+
26+
> ℹ️ `shell_id` and `submodel_id` are base64-encoded automatically unless you pass `encode=False`.
27+
28+
---
29+
30+
## 📦 Uploading
31+
32+
```python
33+
shellsmith.upload_aas("example.aasx")
34+
shellsmith.upload_aas_folder("my-aas-folder/")
35+
```
36+
37+
---
38+
39+
## 🗑️ Deleting
40+
41+
```python
42+
shellsmith.delete_shell("https://example.com/shells/abc123")
43+
shellsmith.delete_submodel("https://example.com/submodels/def456")
44+
```
45+
46+
---
47+
48+
## 🔗 REST Endpoint Mapping
49+
50+
### 🔹 Shells
51+
52+
| Method | Endpoint | Function |
53+
|--------|------------------------------------------------------------|------------------------|
54+
| GET | `/shells` | `get_shells` |
55+
| POST | `/shells` | `post_shell` |
56+
| GET | `/shells/{aasIdentifier}` | `get_shell` |
57+
| PUT | `/shells/{aasIdentifier}` | `put_shell` |
58+
| DELETE | `/shells/{aasIdentifier}` | `delete_shell` |
59+
| GET | `/shells/{aasIdentifier}/submodel-refs` | `get_submodel_refs` |
60+
| POST | `/shells/{aasIdentifier}/submodel-refs` | `post_submodel_ref` |
61+
| DELETE | `/shells/{aasIdentifier}/submodel-refs/{submodelId}` | `delete_submodel_ref`|
62+
63+
---
64+
65+
### 🔸 Submodels
66+
67+
| Method | Endpoint | Function |
68+
|--------|-----------------------------------------------|--------------------------|
69+
| GET | `/submodels` | `get_submodels` |
70+
| POST | `/submodels` | `post_submodel` |
71+
| GET | `/submodels/{submodelId}` | `get_submodel` |
72+
| PUT | `/submodels/{submodelId}` | `put_submodel` |
73+
| DELETE | `/submodels/{submodelId}` | `delete_submodel` |
74+
| GET | `/submodels/{submodelId}/$value` | `get_submodel_value` |
75+
| PATCH | `/submodels/{submodelId}/$value` | `patch_submodel_value` |
76+
| GET | `/submodels/{submodelId}/$metadata` | `get_submodel_metadata`|
77+
78+
---
79+
80+
### 🔻 Submodel Elements
81+
82+
| Method | Endpoint | Function |
83+
|--------|------------------------------------------------------------------------|--------------------------------|
84+
| GET | `/submodels/{submodelId}/submodel-elements` | `get_submodel_elements` |
85+
| POST | `/submodels/{submodelId}/submodel-elements` | `post_submodel_element` |
86+
| GET | `/submodels/{submodelId}/submodel-elements/`<br>`{idShortPath}` | `get_submodel_element` |
87+
| PUT | `/submodels/{submodelId}/submodel-elements/`<br>`{idShortPath}` | `put_submodel_element` |
88+
| POST | `/submodels/{submodelId}/submodel-elements/`<br>`{idShortPath}` | `post_submodel_element` |
89+
| DELETE | `/submodels/{submodelId}/submodel-elements/`<br>`{idShortPath}` | `delete_submodel_element` |
90+
| GET | `/submodels/{submodelId}/submodel-elements/`<br>`{idShortPath}/$value` | `get_submodel_element_value` |
91+
| PATCH | `/submodels/{submodelId}/submodel-elements/`<br>`{idShortPath}/$value` | `patch_submodel_element_value` |
92+
93+
---
94+
95+
### 📦 Upload
96+
97+
| Method | Endpoint | Function |
98+
|--------|-----------|-----------------------------------------|
99+
| POST | `/upload` | `upload_aas` <br> `upload_aas_folder` |
100+
101+
> 📁 Upload functions are provided via the `shellsmith.upload` submodule.
102+
103+
---
104+
105+
## 🛠️ Advanced Utilities (`shellsmith.services`)
106+
107+
The `services` module provides high-level operations for bulk management, cleanup, and environment diagnostics.
108+
109+
### 🔁 Submodel Utilities
110+
111+
```python
112+
from shellsmith import services
113+
```
114+
115+
#### `get_shell_submodels(shell_id)`
116+
Returns all submodels associated with a given shell. Skips missing submodels with a warning.
117+
118+
#### `delete_submodels_of_shell(shell_id)`
119+
Deletes all submodels referenced by the given shell.
120+
121+
#### `remove_submodel_references(submodel_id)`
122+
Unlinks the given submodel from all referencing shells.
123+
124+
#### `remove_dangling_submodel_refs()`
125+
Finds and removes all submodel references that point to non-existent submodels.
126+
127+
---
128+
129+
### ☢️ Destructive Helpers
130+
131+
#### `delete_shell_cascading(shell_id)`
132+
Deletes a shell *and* all its associated submodels. Use with caution.
133+
134+
#### `delete_all_shells()`
135+
Deletes all Asset Administration Shells in the environment.
136+
137+
#### `delete_all_submodels()`
138+
Deletes all Submodels in the environment.
139+
140+
---
141+
142+
### 🧹 Cleanup & Diagnostics
143+
144+
#### `find_unreferenced_submodels()`
145+
Returns all submodel IDs that are not referenced by any shell.
146+
147+
#### `find_dangling_submodel_refs()`
148+
Returns all shells with broken submodel references (e.g. pointing to deleted submodels).
149+
150+
#### `health()`
151+
Checks the BaSyx environment health. Returns `"UP"` or `"DOWN"`.
152+
153+
---
154+
155+
## 📚 Reference
156+
157+
- 🔗 [Plattform Industrie 4.0 Swagger Docs](https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection)

0 commit comments

Comments
 (0)