Add initial documentation (#12)

* add initial documentation

---------

Co-authored-by: Tino Bischoff <[email protected]>
Co-authored-by: fvolz <[email protected]>

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: '3.11'
+
+sphinx:
+  configuration: docs/source/conf.py
+  #fail_on_warning: true
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CONTRIBUTING.md

@@ -0,0 +1,24 @@
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions are **greatly appreciated**.
+
+If you have a suggestion for improvements, please fork the repo and create a pull request. You can also simply open an issue.
+Don't forget to rate the project! Thanks again!
+
+1.  Fork the Project
+2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4.  Push to the Branch (`git push origin feature/AmazingFeature`)
+5.  Open a Pull Request
+
+### Code Formatting
+The project uses *spotless:check* in the build cycle, which means the project only compiles if all code, *.pom and *.xml files are formatted according to the project's codestyle definitions (see details on [spotless](https://github.com/diffplug/spotless)).
+You can automatically format your code by running
+
+> mvn spotless:apply
+
+Additionally, you can import the eclipse formatting rules defined in */codestyle* into our IDE.
+
+### Third Party License
+If you use additional dependencies please be sure that the licenses of these dependencies are compliant with our [License](#license). If you are not sure which license your dependencies have, you can run
+> mvn license:aggregate-third-party-report
+
+and check the generated report in the directory `documentation/third_party_licenses_report.html`.

README.md

@@ -1 +1,82 @@
-# FAAAST-Registry
+# FA³ST Registry [![Build Status](https://github.com/FraunhoferIOSB/FAAAST-Registry/workflows/Maven%20Build/badge.svg)](https://github.com/FraunhoferIOSB/FAAAST-Registry/actions) [![Codacy Badge](https://app.codacy.com/project/badge/Grade/c6851106e76e4df782db1d30fe5d846f)](https://www.codacy.com/gh/FraunhoferIOSB/FAAAST-Registry/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=FraunhoferIOSB/FAAAST-Registry&amp;utm_campaign=Badge_Grade) [![Documentation Status](https://readthedocs.org/projects/faaast-registry/badge/?version=latest)](https://faaast-registry.readthedocs.io/en/latest/?badge=latest) <a href="https://sonarcloud.io/summary/new_code?id=FraunhoferIOSB_FAAAST-Registry" ><img src="https://sonarcloud.io/images/project_badges/sonarcloud-white.svg" alt="SonarCloud badge" width="105"/></a>
+
+![FA³ST Registry Logo Light](./docs/source/images/Fa3st-Registry_positiv.png/#gh-light-mode-only "FA³ST Registry Logo")
+![FA³ST Registry Logo Dark](./docs/source/images/Fa3st-Registry_negativ.png/#gh-dark-mode-only "FA³ST Registry Logo")
+
+The **F**raunhofer **A**dvanced **A**sset **A**dministration **S**hell **T**ools (**FA³ST**) Registry.
+
+For more details on FA³ST Registry see the full documenation :blue_book: [here](https://faaast-registry.readthedocs.io/).
+
+| FA³ST Registry is still under development. Contributions in form of issues and pull requests are highly welcome. |
+|-----------------------------|
+
+## Prerequisites
+
+-   Java 17+
+
+## Getting Started
+
+You can find a detailed documentation :blue_book: [here](https://faaast-registry.readthedocs.io/)
+
+## Usage
+
+### Download pre-compiled JAR
+
+<!--start:download-snapshot-->
+[Download latest SNAPSHOT version (0.1.0-SNAPSHOT)](https://oss.sonatype.org/service/local/artifact/maven/redirect?r=snapshots&g=de.fraunhofer.iosb.ilt.faaast.registry&a=service&v=0.1.0-SNAPSHOT)<!--end:download-snapshot-->
+
+### As Maven Dependency
+
+```xml
+<dependency>
+	<groupId>de.fraunhofer.iosb.ilt.faaast.registry</groupId>
+	<artifactId>service</artifactId>
+	<version>0.1.0-SNAPSHOT</version>
+</dependency>
+```
+
+### As Gradle Dependency
+
+```text
+implementation 'de.fraunhofer.iosb.ilt.faaast.registry:service:0.1.0-SNAPSHOT'
+```
+
+## Building from Source
+
+### Prerequisites
+
+-   Maven
+
+```sh
+git clone https://github.com/FraunhoferIOSB/FAAAST-Registry
+cd FAAAST-Registry
+mvn clean install
+```
+
+## Changelog
+
+You can find the detailed changelog [here](docs/source/changelog/changelog.md).
+
+## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions are **greatly appreciated**.
+You can find our contribution guidelines [here](CONTRIBUTING.md)
+
+## Contributors
+
+| Name | Github Account |
+|:--| -- |
+| Michael Jacoby | [mjacoby](https://github.com/mjacoby) |
+| Tino Bischoff | [tbischoff2](https://github.com/tbischoff2) |
+
+## Contact
+
+[email protected]
+
+## License
+
+Distributed under the Apache 2.0 License. See `LICENSE` for more information.
+
+Copyright (C) 2022 Fraunhofer Institut IOSB, Fraunhoferstr. 1, D 76131 Karlsruhe, Germany.
+
+You should have received a copy of the Apache 2.0 License along with this program. If not, see https://www.apache.org/licenses/LICENSE-2.0.html.

core/src/main/java/de/fraunhofer/iosb/ilt/faaast/registry/core/AbstractAasRepository.java

@@ -25,7 +25,7 @@
 
 
 /**
- * Abstratc base class for implementing {@link AasRepository} interface providing helper methods for validation.
+ * Abstract base class for implementing {@link AasRepository} interface providing helper methods for validation.
  */
 public abstract class AbstractAasRepository implements AasRepository {
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,3 @@
+myst_parser
+sphinx-markdown-tables
+sphinx-rtd-theme

docs/source/_static/css/custom.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 75%;
+}

docs/source/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+<link href="{{ pathto("_static/css/custom.css", True) }}" rel="stylesheet" type="text/css">
+{% endblock %}

docs/source/about/about.md

@@ -0,0 +1,16 @@
+# About the Project
+
+This project provides an implemetation of the Registry for the [Asset Administration Shell (AAS)](https://www.plattform-i40.de/SiteGlobals/IP/Forms/Listen/Downloads/EN/Downloads_Formular.html?cl2Categories_TechnologieAnwendungsbereich_name=Verwaltungsschale).
+The Registry provides information about registered AASs, including the endpoint of the AASs.
+
+## Contact
+
+[email protected]
+
+## License
+
+Distributed under the Apache 2.0 License. See `LICENSE` for more information.
+
+Copyright (C) 2023 Fraunhofer Institut IOSB, Fraunhoferstr. 1, D 76131 Karlsruhe, Germany.
+
+You should have received a copy of the Apache 2.0 License along with this program. If not, see [https://www.apache.org/licenses/LICENSE-2.0.html](https://www.apache.org/licenses/LICENSE-2.0.html).

docs/source/about/contributing.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions are **greatly appreciated**.
+
+If you have a suggestion for improvements, please fork the repo and create a pull request. You can also simply open an issue.
+Don't forget to rate the project! Thanks again!
+
+1.  Fork the Project
+2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4.  Push to the Branch (`git push origin feature/AmazingFeature`)
+5.  Open a Pull Request
+
+## Code Formatting
+
+The project uses _spotless:check_ in the build cycle, which means the project only compiles if all code, *.pom and *.xml files are formatted according to the project's codestyle definitions (see details on [spotless](https://github.com/diffplug/spotless)).
+You can automatically format your code by running
+
+> mvn spotless:apply
+
+Additionally, you can import the eclipse formatting rules defined in _/codestyle_ into our IDE.
+
+## Third Party License
+
+If you use additional dependencies please be sure that the licenses of these dependencies are compliant with our License. If you are not sure which license your dependencies have, you can run
+> mvn license:aggregate-third-party-report
+
+and check the generated report in the directory `docs/third_party_licenses_report.html`.
+
+## Contributors
+
+| Name | Github Account |
+|:--| -- |
+| Michael Jacoby | [mjacoby](https://github.com/mjacoby) |
+| Tino Bischoff | [tbischoff2](https://github.com/tbischoff2) |

docs/source/about/recommended.md

@@ -0,0 +1,6 @@
+# Recommended Documents/Links
+
+-   [Asset Administration Shell Specifications](https://industrialdigitaltwin.org/en/content-hub)
+Quicklinks To Different Versions & Reading Guide
+-   [Details of the Asset Administration Shell - Part 2](https://www.plattform-i40.de/IP/Redaktion/EN/Downloads/Publikation/Details_of_the_Asset_Administration_Shell_Part2_V1.html), Nov 2021   
+This part of the AAS specification provides information about the Registry, the descriptors and the available APIs.

docs/source/api/api.md

@@ -0,0 +1,15 @@
+## API
+
+The Registry allows accessing the data via REST-API.
+
+### Supported API calls
+
+-   Asset Administration Shell Registry Interface
+    -   /registry/shell-descriptors ![GET](https://img.shields.io/badge/GET-blue) ![POST](https://img.shields.io/badge/POST-brightgreen)
+    -   /registry/shell-descriptors/{aasIdentifier} ![GET](https://img.shields.io/badge/GET-blue) ![PUT](https://img.shields.io/badge/PUT-orange) ![DELETE](https://img.shields.io/badge/DELETE-red)
+    -   /registry/shell-descriptors/{aasIdentifier}/submodel-descriptors ![GET](https://img.shields.io/badge/GET-blue) ![POST](https://img.shields.io/badge/POST-brightgreen)
+    -   /registry/shell-descriptors/{aasIdentifier}/submodel-descriptors/{submodelIdentifier} ![GET](https://img.shields.io/badge/GET-blue) ![PUT](https://img.shields.io/badge/PUT-orange) ![DELETE](https://img.shields.io/badge/DELETE-red)
+
+-   Submodel Registry Interface
+    -   registry/submodel-descriptors ![GET](https://img.shields.io/badge/GET-blue) ![POST](https://img.shields.io/badge/POST-brightgreen)
+    -   registry/submodel-descriptors/{submodelIdentifier} ![GET](https://img.shields.io/badge/GET-blue) ![PUT](https://img.shields.io/badge/PUT-orange) ![DELETE](https://img.shields.io/badge/DELETE-red)

docs/source/changelog/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+<!--start:changelog-header-->
+## Current development version (0.1.0-SNAPSHOT)<!--end:changelog-header-->
+
+Initial development

docs/source/conf.py

@@ -0,0 +1,43 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information
+
+project = 'FA³ST Registry'
+copyright = '2023, Fraunhofer IOSB'
+author = 'Fraunhofer IOSB'
+
+# -- General configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'myst_parser',
+    'sphinx_markdown_tables'
+]
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+# These folders are copied to the documentation's HTML output
+html_static_path = ['_static']
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/custom.css',
+]

docs/source/gettingstarted/configuration.md

@@ -0,0 +1,5 @@
+# Configuration
+
+## Persistence: In-Memory vs. Database
+
+The default configuration starts the Registry with in-memory persistence. To use relational database persistence with a PostgreSQL database, please refer to the `JPA Persistence` section for details.

docs/source/gettingstarted/docker.md

@@ -0,0 +1,45 @@
+# Usage with Docker
+
+This section describes the usage with docker and docker compose.
+
+## Docker-Compose
+
+Clone this repository, navigate to `/misc/docker/` and run this command inside it.
+
+```sh
+cd misc/docker
+docker-compose up
+```
+
+To modify the configuration edit the file `/misc/docker/docker-compose.yml`.
+You can change the following values using environment variables:
+
+
+### Configuration
+
+| Name                                    | Example Value                                                             | Description                                                  |
+|:----------------------------------------|---------------------------------------------------------------------------|--------------------------------------------------------------|
+| spring.profiles.active                  | default / external                                                        | in-memory or external database connection                    |
+| spring.jpa.properties.hibernate.dialect | org.hibernate.dialect.H2Dialect / org.hibernate.dialect.PostgreSQLDialect | the hibernate dialect to be used for the database connection |
+| spring.datasource.driver                | org.h2.Driver / org.postgresql.Driver                                     | the JDBC driver to be used for the database connection       |
+| spring.datasource.url                   | jdbc:postgresql://db:5432/postgres                                        | url of the internal or external database                     |
+| spring.datasource.username              | postgres                                                                  | username for the database                                    |
+| spring.datasource.password              | admin                                                                     | password for the database                                    |
+| server.port                             | 8090 | port of the Registry                                         |
+
+## Docker CLI
+
+To start the FA³ST Registry with default values execute this command.
+A FA³ST Registry with in-memory database on port 8090 will be started.
+
+```sh
+docker run --rm -P fraunhoferiosb/faaast-registry
+```
+
+To start the FA³ST Registry with your own configuration, override the environment variables.
+
+```sh
+docker run --rm -P -e "server.port=8091" fraunhoferiosb/faaast-registry
+```
+
+Similarly to the above examples you can pass more arguments to the FA³ST Registry by using the CLI or an environment file