Skip to content
This repository was archived by the owner on Feb 15, 2024. It is now read-only.

Commit 292be59

Browse files
Daespenweissarn
Daespen
and
weissarn
authored
Add documentation source files (#33)
* Add documentation source files - possibility to use DocFX for static site generation * Link from Readme to gh-pages page Co-authored-by: weissarn <arno.weiss@iwu.fraunhofer.de>
1 parent dbb7d00 commit 292be59

16 files changed

Lines changed: 235 additions & 0 deletions

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ the document 'Details of the Asset Administration Shell', published on
99

1010
# Build and Use
1111

12+
Some examples can be found on the [documentation webpage](https://admin-shell-io.github.io/java-serializer/).
13+
1214
You can build the project using Maven by simply executing at the repository
1315
root:
1416

@@ -37,6 +39,8 @@ The project contains several modules:
3739
- `dataformat-uanodeset` OPC UA I4AAS NodeSet de-/serializer
3840
- `dataformat-aml` AutomationML serializer (deserializer is currently under development)
3941

42+
Additionally, the sources that are used for generating the static documentation using [DocFX](https://dotnet.github.io/docfx/) in the `gh-pages` branch are located in the `docs` folder.
43+
4044

4145

4246
# How to Contribute

‎docs/.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
###############
2+
# folder #
3+
###############
4+
/**/DROP/
5+
/**/TEMP/
6+
/**/packages/
7+
/**/bin/
8+
/**/obj/
9+
_site

‎docs/articles/building.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Building
2+
3+
You can download and build the repository by yourself by following these steps:
4+
5+
- Clone the GitHub repository:
6+
7+
```sh
8+
git clone https://github.com/admin-shell-io/aasx-package-explorer
9+
```
10+
11+
- Use [Maven](https://maven.apache.org/) to build the project
12+
```sh
13+
mvn clean package
14+
```
15+
16+
- **OR** use Maven to build and install the artifacts in your local Maven repository
17+
```sh
18+
mvn clean install
19+
```
20+
21+
> [!NOTE]
22+
>
23+
> If the project is built locally, the artifact version is set to the `revision` variable in the `pom.xml` in the project root folder.
24+
> ```xml
25+
> <revision>1.1.0</revision>
26+
> <model.version>${revision}</model.version>
27+
> ```
28+
> If you change the version of your local built, the `model.version` is also set to the updated artifact version from the [java-model](https://github.com/admin-shell-io/java-model) project. For the same version number, both artifacts are compatible.

‎docs/articles/development_workflow.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Development Workflow
2+
3+
We develop with Github using pull requests (see this [Github guide](https://guides.github.com/introduction/flow/) for a short introduction).
4+
5+
**Development branch.** The development branch is always `master`. Expect changes on this branch from time to time.
6+
7+
**Releases.** The releases mark the development milestones on the `master` branch with a certain feature completeness.
8+
9+
## Pull Requests
10+
11+
**Feature branches.** We develop using the feature branches, see this [section of the Git book](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows). We use `feature/'feature-name'` and `bugfix/'bugfix-name'` as a naming convention.
12+
13+
If you are a member of the development team, create a feature branch directly within the repository.
14+
15+
Otherwise, if you are a non-member contributor, fork the repository and create the feature branch in your forked repository. See this Github tuturial for more guidance.
16+
17+
**Branch Prefix.** Each PullRequest must contained a list of the changed topics, for instance as a list of bulletpoints. Simply refering to the commit messages is not sufficient.
18+
19+
**Reviews.** Each PullRequest is reviewed by the Maintainers of the project. In order to simplify the workflow, please assign the PullRequest directly to the Maintainer you think is most knowledgable about your changes.
20+
21+
## Commit Messages
22+
23+
The commit messages should follow the guidelines from https://chris.beams.io/posts/git-commit:
24+
25+
- Separate subject from body with a blank line
26+
- Limit the subject line to 50 characters
27+
- Capitalize the subject line
28+
- Do not end the subject line with a period
29+
- Use the imperative mood in the subject line
30+
- Wrap the body at 72 characters
31+
- Use the body to explain what and why (instead of how)

‎docs/articles/intro.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Introduction
2+
3+
The [AAS Java Dataformat Library](https://github.com/admin-shell-io/java-serializer/) is a collection of software modules to serialize and deserialze instances of the Asset Administration Shell from and to Java instances. De-/serialization works according to the dataformat schemas published in the document 'Details of the Asset Administration Shell', published on www.plattform-i40.de.
4+
5+
The serialization library and all its modules depend on the Java implementation for the metamodel from the project [java-model](https://github.com/admin-shell-io/java-model).
6+
7+
## Project Structure
8+
9+
The project contains several modules:
10+
11+
- `dataformat-parent` Maven parent module that contains the respective de-/serializers for the different data formats.
12+
- `dataformat-core` Location of the general classes and interfaces that are used by more than one de-/serializer.
13+
- `dataformat-aasx` AASX de-/serializer
14+
- `dataformat-json` JSON de-/serializer
15+
- `dataformat-xml` XML de-/serializer
16+
- `dataformat-uanodeset` OPC UA I4AAS NodeSet de-/serializer

‎docs/articles/releasing.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Versioning
2+
3+
We version using **semantic versioning** (e.g., `1.0.4`). The first position indicates the major release. Different major releases canvas contain breaking changes and are not necessarily compliant. The second number indicates the minor releas or revision, which contains new features compared to an older revision. The last position is used for hotfixes or bugfixes.
4+
5+
Note, that the versioning scheme of this project is not directly aligned with the release process of the metamodel! For instance, the version 1.0.3 targets the metamodel version 3.0.RC02

‎docs/articles/toc.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
- name: Introduction
2+
href: intro.md
3+
- name: Usage
4+
href: usage.md
5+
- name: Building
6+
href: building.md
7+
- name: Development Workflow
8+
href: development_workflow.md
9+
- name: Releasing
10+
href: releasing.md

‎docs/articles/usage.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Usage
2+
3+
The library and its modules are released at Maven Central. Thus, you can use the respective serializers in your Java Maven project by adding the following dependency:
4+
5+
```xml
6+
<dependency>
7+
<groupId>io.admin-shell.aas</groupId>
8+
<artifactId>dataformat-**serializer**</artifactId>
9+
<version>**version**</version>
10+
<dependency>
11+
```
12+
13+
For example, uses the following dependency declaration to embed the `JSON dataformat`:
14+
15+
```xml
16+
<dependency>
17+
<groupId>io.admin-shell.aas</groupId>
18+
<artifactId>dataformat-json</artifactId>
19+
<version>1.1.1</version>
20+
<dependency>
21+
```
22+
23+
24+
> [!NOTE]
25+
>
26+
> Maven will automatically resolve the dependencies of the library and therefore also include the model implementation from the [java-model](https://github.com/admin-shell-io/java-model) project.
27+
28+
## Serialization
29+
30+
The library supports serialization of an AAS environment to a `File`, `OutputStream` or `String`. See the following interface to get more details on what methods can be used to serialize an environment:
31+
32+
https://github.com/admin-shell-io/java-serializer/blob/main/dataformat-core/src/main/java/io/adminshell/aas/v3/dataformat/Serializer.java
33+
34+
Here is a small example on how to serialize a given environment to a JSON-`String`:
35+
36+
```Java
37+
AssetAdministrationShellEnvironment env = ...;
38+
String serializedEnvironment = new JsonSerializer().write(env);
39+
```
40+
41+
## Deserialization
42+
43+
Likewise, you can deserialize an AAS environment from a `File`, `InputStream` or `String`. See the following interface to get more details on what methods can be used to deserialize an environment:
44+
45+
https://github.com/admin-shell-io/java-serializer/blob/main/dataformat-core/src/main/java/io/adminshell/aas/v3/dataformat/Deserializer.java
46+
47+
Here is a small example on how to deserialize a given JSON-`String` and draw some information out of the returned model:
48+
49+
```Java
50+
String serializedEnvironment = "...";
51+
AssetAdministrationShellEnvironment env = new JsonDeserializer().read(serializedEnvironment);
52+
List<AssetAdministrationShell> aasList = env.getAssetAdministrationShells();
53+
aasList.forEach(aas -> System.out.println("Environment contains AAS: " + aas.getIdShort()));
54+
```
55+
56+
## AASX
57+
58+
In order to be able to also embed files into a serialized environment, it is possible to create an .aasx-package. The AASX module makes use of the xml-dataformat to handle the `AASEnvironment`.
59+
60+
```Java
61+
byte[] fileContent = ...;
62+
AssetAdministrationShellEnvironment env = ...;
63+
InMemoryFile file = new InMemoryFile(fileContent, "aasx/MyFile.pdf");
64+
List<InMemoryFile> fileList = new ArrayList<>()
65+
fileList.add(file);
66+
ByteArrayOutputStream out = new ByteArrayOutputStream();
67+
new AASXSerializer().write(env, fileList, out);
68+
```
69+
70+
> [!NOTE]
71+
>
72+
> The given filepath is relative to the .aasx package root and has to correspondent to the relative path given in the `File`-`SubmodelElement` that points to this file.
73+
74+
## Constraint Validation
75+
76+
According to the AAS specification in "Details of The Asset Administration Shell", there are a number of constraints a valid model has to fulfill. The java-model implementation allows the creation of models that are not valid according to these constraints. The java-dataformat library contains a validation module to test them. The following snippet shows a submodel with an invalid idShort. Therefore, this snippet will throw a `ValidationException`.
77+
78+
```Java
79+
Referable invalidReferable = new DefaultSubmodel.Builder()
80+
.identification(
81+
new DefaultIdentifier.Builder().identifier("submodel").idType(IdentifierType.CUSTOM).build())
82+
.idShort("_idShort")
83+
.build();
84+
ShaclValidator.getInstance().validate(invalidReferable);
85+
```

‎docs/docfx.json‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
{
2+
"build": {
3+
"content": [
4+
{
5+
"files": [
6+
"articles/**.md",
7+
"**/*.yml",
8+
"*.md",
9+
"toc.yml"
10+
]
11+
}
12+
],
13+
"resource": [
14+
{
15+
"files": [
16+
"images/**"
17+
]
18+
}
19+
],
20+
"dest": "_site",
21+
"globalMetadata": {
22+
"_appTitle": "java-serializer Documentation",
23+
"_appFaviconPath": "images/favicon.ico",
24+
"_appLogoPath": "images/adminshellio-48x48.jpg",
25+
"_enableSearch": true
26+
},
27+
"globalMetadataFiles": [],
28+
"fileMetadataFiles": [],
29+
"template": [
30+
"default"
31+
],
32+
"postProcessors": [],
33+
"markdownEngineName": "markdig",
34+
"noLangKeyword": false,
35+
"keepFileLink": false,
36+
"cleanupCacheHistory": false,
37+
"disableGitFeatures": false
38+
}
39+
}

‎docs/images/adminshellio-48x48.jpg‎

2.18 KB
Loading

0 commit comments

Comments
 (0)