From 46f36d9481fa51d4e907e012130cf0062b756bbc Mon Sep 17 00:00:00 2001 From: Marko Ristin-Kaufmann Date: Wed, 28 Oct 2026 16:01:59 +0100 Subject: [PATCH] Publish docs on GitHub Pages instead of readthedocs We move the documentation from readthedocs to GitHub Pages. The docs workflow now builds and tests the docs on every push and pull request, and deploys them to GitHub Pages on pushes to main. --- .github/workflows/build-test-docs.yml | 43 ++++++++++++-- .readthedocs.yml | 27 --------- README.rst | 8 +-- docs/source/api/common.rst | 8 +++ docs/source/api/constants.rst | 8 +++ docs/source/api/index.rst | 21 +++++++ docs/source/api/jsonization.rst | 8 +++ docs/source/api/jsonvalueverification.rst | 8 +++ docs/source/api/reporting.rst | 8 +++ docs/source/api/stringification.rst | 8 +++ docs/source/api/types.rst | 8 +++ docs/source/api/verification.rst | 8 +++ docs/source/api/xmlcommon.rst | 8 +++ docs/source/api/xmlization.rst | 8 +++ docs/source/api/xmlrpc.rst | 8 +++ docs/source/conf.py | 5 ++ .../source/getting_started/create_get_set.rst | 10 ++-- docs/source/getting_started/install.rst | 2 +- .../getting_started/iterate_and_transform.rst | 42 +++++++------- docs/source/getting_started/jsonize.rst | 20 +++---- docs/source/getting_started/verify.rst | 16 ++--- docs/source/getting_started/xmlize.rst | 58 +++++++++---------- docs/source/index.rst | 2 +- docs/source/introduction.rst | 4 +- pyproject.toml | 1 + 25 files changed, 234 insertions(+), 113 deletions(-) delete mode 100644 .readthedocs.yml create mode 100644 docs/source/api/common.rst create mode 100644 docs/source/api/constants.rst create mode 100644 docs/source/api/index.rst create mode 100644 docs/source/api/jsonization.rst create mode 100644 docs/source/api/jsonvalueverification.rst create mode 100644 docs/source/api/reporting.rst create mode 100644 docs/source/api/stringification.rst create mode 100644 docs/source/api/types.rst create mode 100644 docs/source/api/verification.rst create mode 100644 docs/source/api/xmlcommon.rst create mode 100644 docs/source/api/xmlization.rst create mode 100644 docs/source/api/xmlrpc.rst diff --git a/.github/workflows/build-test-docs.yml b/.github/workflows/build-test-docs.yml index cffd57b..398b809 100644 --- a/.github/workflows/build-test-docs.yml +++ b/.github/workflows/build-test-docs.yml @@ -6,19 +6,25 @@ on: tags: [ "**" ] pull_request: branches: [ "**" ] + workflow_dispatch: + +permissions: + contents: read jobs: - Execute: + Build-and-test: runs-on: ubuntu-latest strategy: matrix: + # NOTE: sphinx-paramlinks depends on distutils, which has been removed + # in Python 3.12. python-version: ['3.10'] steps: - - uses: actions/checkout@master + - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} @@ -30,8 +36,35 @@ jobs: - name: Build the docs run: | - sphinx-build docs/source docs/build + sphinx-build -W --keep-going docs/source docs/build - name: Test the docs run: | - sphinx-build docs/source docs/build -b doctest + sphinx-build docs/source docs/build-doctest -b doctest + + - name: Upload the docs as a Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/build + + Deploy: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: Build-and-test + runs-on: ubuntu-latest + + permissions: + pages: write + id-token: write + + concurrency: + group: pages + cancel-in-progress: false + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index b407e63..0000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,27 +0,0 @@ -# .readthedocs.yml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required -version: 2 - -# Set the version of Python and other tools you might need -build: - os: ubuntu-22.04 - tools: - python: "3.9" - -# Build documentation in the docs/ directory with Sphinx -sphinx: - configuration: docs/source/conf.py - -# Optionally build your docs in additional formats such as PDF -formats: - - pdf - -# Optionally set the version of Python and requirements required to build your docs -python: - install: - - method: pip - path: . - - requirements: docs/requirements.txt diff --git a/README.rst b/README.rst index 01b4f0b..aedea1f 100644 --- a/README.rst +++ b/README.rst @@ -17,13 +17,13 @@ Eclipse aas-core3.2-python .. image:: https://img.shields.io/pypi/pyversions/aas-core3.2.svg :alt: PyPI - Python Version -.. image:: https://readthedocs.org/projects/aas-core32-python/badge/?version=latest - :target: https://aas-core32-python.readthedocs.io/en/latest/?badge=latest +.. image:: https://github.com/eclipse-aascw/aas-core3.2-python/actions/workflows/build-test-docs.yml/badge.svg + :target: https://eclipse-aascw.github.io/aas-core3.2-python/ :alt: Documentation This is a software development kit (SDK) to manipulate, verify and de/serialize Asset Administration Shells based on the version 3.2 of the meta-model. -The documentation is available on: https://aas-core32-python.readthedocs.io/en/latest/. +The documentation is available on: https://eclipse-aascw.github.io/aas-core3.2-python/ The majority of the code has been automatically generated by `aas-core-codegen`_. @@ -31,4 +31,4 @@ If you want to contribute, see our `contributing guide`_. .. _aas-core-codegen: https://github.com/eclipse-aascw/aas-core-codegen -.. _contributing guide: https://aas-core32-python.readthedocs.io/en/latest/contributing.html +.. _contributing guide: https://eclipse-aascw.github.io/aas-core3.2-python/contributing.html diff --git a/docs/source/api/common.rst b/docs/source/api/common.rst new file mode 100644 index 0000000..8264c2c --- /dev/null +++ b/docs/source/api/common.rst @@ -0,0 +1,8 @@ +******************** +aas_core3_2.common +******************** + +.. automodule:: aas_core3_2.common + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/constants.rst b/docs/source/api/constants.rst new file mode 100644 index 0000000..31479d4 --- /dev/null +++ b/docs/source/api/constants.rst @@ -0,0 +1,8 @@ +*********************** +aas_core3_2.constants +*********************** + +.. automodule:: aas_core3_2.constants + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 0000000..1ecffd5 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,21 @@ +*** +API +*** + +This is the documentation automatically generated from the source code. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + common + constants + jsonization + jsonvalueverification + reporting + stringification + types + verification + xmlcommon + xmlization + xmlrpc diff --git a/docs/source/api/jsonization.rst b/docs/source/api/jsonization.rst new file mode 100644 index 0000000..231ca97 --- /dev/null +++ b/docs/source/api/jsonization.rst @@ -0,0 +1,8 @@ +************************* +aas_core3_2.jsonization +************************* + +.. automodule:: aas_core3_2.jsonization + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/jsonvalueverification.rst b/docs/source/api/jsonvalueverification.rst new file mode 100644 index 0000000..bda5ea7 --- /dev/null +++ b/docs/source/api/jsonvalueverification.rst @@ -0,0 +1,8 @@ +*********************************** +aas_core3_2.jsonvalueverification +*********************************** + +.. automodule:: aas_core3_2.jsonvalueverification + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/reporting.rst b/docs/source/api/reporting.rst new file mode 100644 index 0000000..b010115 --- /dev/null +++ b/docs/source/api/reporting.rst @@ -0,0 +1,8 @@ +*********************** +aas_core3_2.reporting +*********************** + +.. automodule:: aas_core3_2.reporting + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/stringification.rst b/docs/source/api/stringification.rst new file mode 100644 index 0000000..7281ca8 --- /dev/null +++ b/docs/source/api/stringification.rst @@ -0,0 +1,8 @@ +***************************** +aas_core3_2.stringification +***************************** + +.. automodule:: aas_core3_2.stringification + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst new file mode 100644 index 0000000..999ed4d --- /dev/null +++ b/docs/source/api/types.rst @@ -0,0 +1,8 @@ +******************* +aas_core3_2.types +******************* + +.. automodule:: aas_core3_2.types + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/verification.rst b/docs/source/api/verification.rst new file mode 100644 index 0000000..8034662 --- /dev/null +++ b/docs/source/api/verification.rst @@ -0,0 +1,8 @@ +************************** +aas_core3_2.verification +************************** + +.. automodule:: aas_core3_2.verification + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/xmlcommon.rst b/docs/source/api/xmlcommon.rst new file mode 100644 index 0000000..75a3314 --- /dev/null +++ b/docs/source/api/xmlcommon.rst @@ -0,0 +1,8 @@ +*********************** +aas_core3_2.xmlcommon +*********************** + +.. automodule:: aas_core3_2.xmlcommon + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/xmlization.rst b/docs/source/api/xmlization.rst new file mode 100644 index 0000000..7108ca3 --- /dev/null +++ b/docs/source/api/xmlization.rst @@ -0,0 +1,8 @@ +************************ +aas_core3_2.xmlization +************************ + +.. automodule:: aas_core3_2.xmlization + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__,__subclasshook__,__parameters__ diff --git a/docs/source/api/xmlrpc.rst b/docs/source/api/xmlrpc.rst new file mode 100644 index 0000000..ef3c1c6 --- /dev/null +++ b/docs/source/api/xmlrpc.rst @@ -0,0 +1,8 @@ +******************** +aas_core3_2.xmlrpc +******************** + +.. automodule:: aas_core3_2.xmlrpc + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/conf.py b/docs/source/conf.py index 5e1a0d0..3592721 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -49,6 +49,11 @@ autodoc_typehints = 'signature' +# NOTE: The bare ``>>>`` blocks in the docstrings of the generated modules are +# already doctest'ed in dev/continuous_integration/precommit.py with +# the module namespace. Here we only test the explicit doctest directives. +doctest_test_doctest_blocks = '' + autodoc_default_options = { 'members': True, 'undoc-members': True, diff --git a/docs/source/getting_started/create_get_set.rst b/docs/source/getting_started/create_get_set.rst index 1a2b5bc..9b8f3ae 100644 --- a/docs/source/getting_started/create_get_set.rst +++ b/docs/source/getting_started/create_get_set.rst @@ -2,17 +2,17 @@ Create, Get and Set Properties of an AAS Model ********************************************** -The module :py:mod:`aas_core3_1.types` contains all the data types of the meta-model. +The module :py:mod:`aas_core3_2.types` contains all the data types of the meta-model. This includes enumerations, abstract and concrete classes. -The module :py:mod:`aas_core3_1.types` also contains visitors and transformers, but we will write more about them in :ref:`iterate_and_transform` section. +The module :py:mod:`aas_core3_2.types` also contains visitors and transformers, but we will write more about them in :ref:`iterate_and_transform` section. Creation ======== We use constructors to create an AAS model. -Usually you start bottom-up, all the way up to the :py:class:`aas_core3_1.types.Environment`. +Usually you start bottom-up, all the way up to the :py:class:`aas_core3_2.types.Environment`. Getting and Setting Properties ============================== @@ -28,7 +28,7 @@ For optional properties which come with a default value, we provide special gett If the property is ``None``, this getter will give you the default value. Otherwise, if the property is set, the actual value of the property will be returned. -For example, see :py:meth:`aas_core3_1.types.HasKind.kind_or_default`. +For example, see :py:meth:`aas_core3_2.types.HasKind.kind_or_default`. Example: Create an Environment with a Submodel ============================================== @@ -39,7 +39,7 @@ The submodel will contain two elements, a property and a blob. .. doctest:: - import aas_core3_1.types as aas_types + import aas_core3_2.types as aas_types # Create the first element some_element = aas_types.Property( diff --git a/docs/source/getting_started/install.rst b/docs/source/getting_started/install.rst index 06af336..5c8d479 100644 --- a/docs/source/getting_started/install.rst +++ b/docs/source/getting_started/install.rst @@ -8,4 +8,4 @@ Install the SDK by calling: .. code-block:: - pip3 install aas-core3.1 + pip3 install aas-core3.2 diff --git a/docs/source/getting_started/iterate_and_transform.rst b/docs/source/getting_started/iterate_and_transform.rst index 766aee7..38bc33f 100644 --- a/docs/source/getting_started/iterate_and_transform.rst +++ b/docs/source/getting_started/iterate_and_transform.rst @@ -15,23 +15,23 @@ It gives you an :py:class:`Iterator`. If the property is not set, this getter will yield empty. Otherwise, it will yield from the actual property value. -For example, see :py:meth:`aas_core3_1.types.Environment.over_submodels_or_empty`. +For example, see :py:meth:`aas_core3_2.types.Environment.over_submodels_or_empty`. ``descend_once`` and ``descend`` ================================ -If you are writing a simple script and do not care about the performance, the SDK provides two methods in the most general interface :py:class:`aas_core3_1.types.Class`, :py:meth:`~aas_core3_1.types.Class.descend_once` and :py:meth:`~aas_core3_1.types.Class.descend`, which you can use to loop through the instances. +If you are writing a simple script and do not care about the performance, the SDK provides two methods in the most general interface :py:class:`aas_core3_2.types.Class`, :py:meth:`~aas_core3_2.types.Class.descend_once` and :py:meth:`~aas_core3_2.types.Class.descend`, which you can use to loop through the instances. -Both :py:meth:`~aas_core3_1.types.Class.descend_once` and :py:meth:`~aas_core3_1.types.Class.descend` iterate over referenced children of an instance of :py:class:`~aas_core3_1.types.Class`. -:py:meth:`~aas_core3_1.types.Class.descend_once`, as it names suggests, stops after all the children has been iterated over. -:py:meth:`~aas_core3_1.types.Class.descend` continues recursively to grand-children, grand-grand-children *etc.* +Both :py:meth:`~aas_core3_2.types.Class.descend_once` and :py:meth:`~aas_core3_2.types.Class.descend` iterate over referenced children of an instance of :py:class:`~aas_core3_2.types.Class`. +:py:meth:`~aas_core3_2.types.Class.descend_once`, as it names suggests, stops after all the children has been iterated over. +:py:meth:`~aas_core3_2.types.Class.descend` continues recursively to grand-children, grand-grand-children *etc.* Here is a short example how you can get all the properties from an environment whose ID-short starts with ``another``: .. testcode:: - import aas_core3_1.types as aas_types + import aas_core3_2.types as aas_types # Prepare the environment environment = aas_types.Environment( @@ -71,7 +71,7 @@ Here is a short example how you can get all the properties from an environment w another_property yet_another_property -Iteration with :py:meth:`~aas_core3_1.types.Class.descend_once` and :py:meth:`~aas_core3_1.types.Class.descend` works well if the performance is irrelevant. +Iteration with :py:meth:`~aas_core3_2.types.Class.descend_once` and :py:meth:`~aas_core3_2.types.Class.descend` works well if the performance is irrelevant. However, if the performance matters, this is not a good approach. First, all the children will be visited (even though you need only a small subset). Second, you need to switch with :py:func:`isinstance` on the runtime type, which grows linearly in computational cost with the number of types you switch on. @@ -84,26 +84,26 @@ Visitor `Visitor pattern`_ is a common design pattern in software engineering. We will not explain the details of the pattern here as you can read about in the ample literature in books or in Internet. -The cornerstone of the visitor pattern is `double dispatch`_: instead of casting to the desired type during the iteration, the method :py:meth:`aas_core3_1.types.Class.accept` directly dispatches to the appropriate visitation method. +The cornerstone of the visitor pattern is `double dispatch`_: instead of casting to the desired type during the iteration, the method :py:meth:`aas_core3_2.types.Class.accept` directly dispatches to the appropriate visitation method. .. _Visitor pattern: https://en.wikipedia.org/wiki/Visitor_pattern .. _double dispatch: https://en.wikipedia.org/wiki/Double_dispatch This allows us to spare runtime type switches and directly dispatch the execution. -The SDK already implements :py:meth:`~aas_core3_1.types.Class.accept` methods, so you only have to implement the visitor. +The SDK already implements :py:meth:`~aas_core3_2.types.Class.accept` methods, so you only have to implement the visitor. The visitor class has a visiting method for each class of the meta-model. In the SDK, we provide different flavors of the visitor abstract classes which you can readily implement: -* :py:class:`~aas_core3_1.types.AbstractVisitor` which needs all the visit methods to be implemented, -* :py:class:`~aas_core3_1.types.PassThroughVisitor` which visits all the elements and does nothing, and -* :py:class:`~aas_core3_1.types.AbstractVisitorWithContext` which propagates a context object along the iteration. +* :py:class:`~aas_core3_2.types.AbstractVisitor` which needs all the visit methods to be implemented, +* :py:class:`~aas_core3_2.types.PassThroughVisitor` which visits all the elements and does nothing, and +* :py:class:`~aas_core3_2.types.AbstractVisitorWithContext` which propagates a context object along the iteration. -Let us re-write the above example related to :py:meth:`~aas_core3_1.types.Class.descend` method with a visitor pattern: +Let us re-write the above example related to :py:meth:`~aas_core3_2.types.Class.descend` method with a visitor pattern: .. testcode:: - import aas_core3_1.types as aas_types + import aas_core3_2.types as aas_types class Visitor(aas_types.PassThroughVisitor): def visit_property(self, that: aas_types.Property): @@ -147,11 +147,11 @@ Expected output: another_property yet_another_property -There are important differences to iteration with :py:meth:`~aas_core3_1.types.Class.descend`: +There are important differences to iteration with :py:meth:`~aas_core3_2.types.Class.descend`: * Due to `double dispatch`_, we spare a cast. This is usually more efficient. -* The iteration logic in :py:meth:`~aas_core3_1.types.Class.descend` lives very close to where it is executed. +* The iteration logic in :py:meth:`~aas_core3_2.types.Class.descend` lives very close to where it is executed. In contrast, the visitor needs to be defined as a separate class. While sometimes faster, writing the visitor makes the code less readable. @@ -159,7 +159,7 @@ Descend or Visitor? =================== In general, people familiar with the `visitor pattern`_ and object-oriented programming will prefer, obviously, visitor class. -People who like functional programming, generator expressions and ilks will prefer :py:meth:`~aas_core3_1.types.Class.descend`. +People who like functional programming, generator expressions and ilks will prefer :py:meth:`~aas_core3_2.types.Class.descend`. It is difficult to discuss different tastes, so you should probably come up with explicit code guidelines in your code and stick to them. @@ -173,11 +173,11 @@ It is very common in compiler design, where the abstract syntax tree is transfor The SDK provides different flavors of a transformer: -* :py:class:`~aas_core3_1.types.AbstractTransformer`, where the model element is directly transformed into something, and -* :py:class:`~aas_core3_1.types.AbstractTransformerWithContext`, which propagates the context object along the transformations. +* :py:class:`~aas_core3_2.types.AbstractTransformer`, where the model element is directly transformed into something, and +* :py:class:`~aas_core3_2.types.AbstractTransformerWithContext`, which propagates the context object along the transformations. Usually you implement for each concrete class how it should be transformed. -If you want to specify only a subset of transformations, and provide the default value for the remainder, the SDK provides :py:class:`~aas_core3_1.types.TransformerWithDefault` and :py:class:`~aas_core3_1.types.TransformerWithDefaultAndContext`. +If you want to specify only a subset of transformations, and provide the default value for the remainder, the SDK provides :py:class:`~aas_core3_2.types.TransformerWithDefault` and :py:class:`~aas_core3_2.types.TransformerWithDefaultAndContext`. We deliberately omit an example due to the length of the code. -Please let us know by `creating an issue `__ if you would like to have an example here. +Please let us know by `creating an issue `__ if you would like to have an example here. diff --git a/docs/source/getting_started/jsonize.rst b/docs/source/getting_started/jsonize.rst index 4385ddf..ab6b3db 100644 --- a/docs/source/getting_started/jsonize.rst +++ b/docs/source/getting_started/jsonize.rst @@ -2,12 +2,12 @@ JSON De/serialization ********************* -Our SDK handles the de/serialization of the AAS models from and to JSON format through the module :py:mod:`aas_core3_1.jsonization`. +Our SDK handles the de/serialization of the AAS models from and to JSON format through the module :py:mod:`aas_core3_2.jsonization`. Serialize ========= -To serialize, you call the function :py:func:`aas_core3.jsonization.to_jsonable` on an instance of :py:class:`aas_core3_1.types.Environment` which will convert it to a JSON-able mapping. +To serialize, you call the function :py:func:`aas_core3_2.jsonization.to_jsonable` on an instance of :py:class:`aas_core3_2.types.Environment` which will convert it to a JSON-able mapping. Here is a snippet that converts the environment first into a JSON-able mapping, and next converts the JSON-able mapping to text: @@ -15,8 +15,8 @@ Here is a snippet that converts the environment first into a JSON-able mapping, import json - import aas_core3_1.types as aas_types - import aas_core3_1.jsonization as aas_jsonization + import aas_core3_2.types as aas_types + import aas_core3_2.jsonization as aas_jsonization # Prepare the environment environment = aas_types.Environment( @@ -64,8 +64,8 @@ Expected output: De-serialize ============ -Our SDK can convert a JSON-able mapping back to an instance of :py:class:`aas_core3_1.types.Environment`. -To that end, you call the function :py:func:`aas_core3_1.jsonization.environment_from_jsonable`. +Our SDK can convert a JSON-able mapping back to an instance of :py:class:`aas_core3_2.types.Environment`. +To that end, you call the function :py:func:`aas_core3_2.jsonization.environment_from_jsonable`. Here is an example snippet: @@ -74,7 +74,7 @@ Here is an example snippet: import json - import aas_core3_1.jsonization as aas_jsonization + import aas_core3_2.jsonization as aas_jsonization text = """\ { @@ -106,12 +106,12 @@ Expected output: .. testoutput:: - - + + Errors ====== -If there are any errors during the de-serialization, an :py:class:`aas_core3_1.jsonization.DeserializationException` will be thrown. +If there are any errors during the de-serialization, an :py:class:`aas_core3_2.jsonization.DeserializationException` will be thrown. Errors occur whenever we encounter invalid JSON values. For example, this is the case when the de-serialization function expects a JSON object, but encounters a JSON array instead. diff --git a/docs/source/getting_started/verify.rst b/docs/source/getting_started/verify.rst index 1fd1972..321ebee 100644 --- a/docs/source/getting_started/verify.rst +++ b/docs/source/getting_started/verify.rst @@ -4,16 +4,16 @@ Verify Our SDK allows you to verify that a model satisfies the constraints of the meta-model. -The verification logic is concentrated in the module :py:mod:`aas_core3_1.verification`, and all it takes is a call to :py:func:`aas_core3_1.verification.verify` function. -The function :py:func:`aas_core3_1.verification.verify` will check that constraints in the given model element are satisfied, including the recursion into children elements. -The function returns an iterator of :py:class:`aas_core3_1.verification.Error`'s, which you can use for further processing (*e.g.*, report to the user). +The verification logic is concentrated in the module :py:mod:`aas_core3_2.verification`, and all it takes is a call to :py:func:`aas_core3_2.verification.verify` function. +The function :py:func:`aas_core3_2.verification.verify` will check that constraints in the given model element are satisfied, including the recursion into children elements. +The function returns an iterator of :py:class:`aas_core3_2.verification.Error`'s, which you can use for further processing (*e.g.*, report to the user). Here is a short example snippet: .. testcode:: - import aas_core3_1.types as aas_types - import aas_core3_1.verification as aas_verification + import aas_core3_2.types as aas_types + import aas_core3_2.verification as aas_verification # Prepare the environment environment = aas_types.Environment( @@ -40,12 +40,12 @@ Expected output: .. testoutput:: - .submodels[0].submodel_elements[0].id_short: ID-short of Referables shall only feature letters, digits, hyphen (``-``) and underscore (``_``); starting mandatory with a letter, and not ending with a hyphen, *I.e.* ``^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$``. + .submodels[0].submodel_elements[0].id_short: AASd-002: ID-short of Referables shall consist of at least two characters and shall only feature letters, digits, hyphen (``-``) and underscore (``_``); starting mandatory with a letter, and not ending with a hyphen, *I.e.* ``^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$``. Limit the Number of Reported Errors =================================== -Since the function :py:func:`aas_core3_1.verification.verify` gives you an iterator, you can use :py:mod:`itertools` on it. +Since the function :py:func:`aas_core3_2.verification.verify` gives you an iterator, you can use :py:mod:`itertools` on it. Here is a snippet which reports only the first 10 errors: @@ -70,4 +70,4 @@ Some constraints require external dependencies such as an AAS registry. Verifying the constraints with external dependencies is out-of-scope of our SDK, as we still lack standardized interfaces to those dependencies. However, all the constraints which need no external dependency are verified. -For a full list of exception, please see the description of the module :py:mod:`aas_core3_1.types`. +For a full list of exception, please see the description of the module :py:mod:`aas_core3_2.types`. diff --git a/docs/source/getting_started/xmlize.rst b/docs/source/getting_started/xmlize.rst index 791e26b..67b34d4 100644 --- a/docs/source/getting_started/xmlize.rst +++ b/docs/source/getting_started/xmlize.rst @@ -2,21 +2,21 @@ XML De/serialization ******************** -The code that de/serializes AAS models from and to XML documents lives in the module :py:mod:`aas_core3_1.xmlization`. +The code that de/serializes AAS models from and to XML documents lives in the module :py:mod:`aas_core3_2.xmlization`. Serialize ========= -You serialize the AAS model to XML-encoded text by calling the function :py:func:`aas_core3_1.xmlization.to_str`. +You serialize the AAS model to XML-encoded text by calling the function :py:func:`aas_core3_2.xmlization.to_str`. -If you want the same text to be written incrementally to a :py:class:`typing.TextIO` stream, you can use the function :py:func:`aas_core3_1.xmlization.write`. +If you want the same text to be written incrementally to a :py:class:`typing.TextIO` stream, you can use the function :py:func:`aas_core3_2.xmlization.write`. Here is an example snippet: .. testcode:: - import aas_core3_1.types as aas_types - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.types as aas_types + import aas_core3_2.xmlization as aas_xmlization # Prepare the environment environment = aas_types.Environment( @@ -43,7 +43,7 @@ Expected output: .. testoutput:: - some-unique-global-identifiersome_propertyxs:int1984 + some-unique-global-identifiersome_propertyxs:int1984 De-serialize @@ -51,19 +51,19 @@ De-serialize You can de-serialize an environment from XML coming from four different sources by using different functions: -* :py:func:`aas_core3_1.xmlization.environment_from_iterparse`, where a stream coming from :py:func:`xml.etree.ElementTree.iterparse` is expected with ``events`` set to ``["start", "end"]``, -* :py:func:`aas_core3_1.xmlization.environment_from_stream`, which expects a textual stream behaving according to :py:class:`typing.TextIO`, -* :py:func:`aas_core3_1.xmlization.environment_from_file`, which expects a path to the file containing the XML of the environment, or -* :py:func:`aas_core3.xmlization.environment_from_str`, which de-serialized the environment from an XML-encoded string. +* :py:func:`aas_core3_2.xmlization.environment_from_iterparse`, where a stream coming from :py:func:`xml.etree.ElementTree.iterparse` is expected with ``events`` set to ``["start", "end"]``, +* :py:func:`aas_core3_2.xmlization.environment_from_stream`, which expects a textual stream behaving according to :py:class:`typing.TextIO`, +* :py:func:`aas_core3_2.xmlization.environment_from_file`, which expects a path to the file containing the XML of the environment, or +* :py:func:`aas_core3_2.xmlization.environment_from_str`, which de-serialized the environment from an XML-encoded string. -Here is a snippet which parses XML as text and then de-serializes it into an instance of :py:class:`~aas_core3_1.types.Environment`: +Here is a snippet which parses XML as text and then de-serializes it into an instance of :py:class:`~aas_core3_2.types.Environment`: .. testcode:: - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( - "" + + "" + "" + "some-unique-global-identifier" + "someProperty" + @@ -80,18 +80,18 @@ Expected output: .. testoutput:: - - + + You can also de-serialize other model classes other than ``Environment``. -For example, to de-serialize a submodel, you can use :py:func:`aas_core3_1.xmlization.submodel_from_str`: +For example, to de-serialize a submodel, you can use :py:func:`aas_core3_2.xmlization.submodel_from_str`: .. testcode:: - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( - "" + + "" + "some-unique-global-identifier" + "someProperty" + "xs:boolean" + @@ -107,18 +107,18 @@ Expected output: .. testoutput:: - + -If you do not know the model type in advance, you can use the general functions such as :py:func:`aas_core3_1.xmlization.from_str` and :py:func:`aas_core3_1.xmlization.from_file`. +If you do not know the model type in advance, you can use the general functions such as :py:func:`aas_core3_2.xmlization.from_str` and :py:func:`aas_core3_2.xmlization.from_file`. The model type will be determined based on the first start element. The same example above can be thus rewritten: .. testcode:: - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( - "" + + "" + "some-unique-global-identifier" + "someProperty" + "xs:boolean" + @@ -134,15 +134,15 @@ Expected output: .. testoutput:: - + -Prefer the particular de-serialization (:py:func:`aas_core3_1.xmlization.submodel_from_str`) whenever you know the type in advance. +Prefer the particular de-serialization (:py:func:`aas_core3_2.xmlization.submodel_from_str`) whenever you know the type in advance. The particular de-serialization function will check the actual model type for you, and you also get more precise type annotations for your downstream code. Errors ====== -If the XML document comes in an unexpected form, our SDK throws a :py:class:`aas_core3_1.xmlization.DeserializationException`. +If the XML document comes in an unexpected form, our SDK throws a :py:class:`aas_core3_2.xmlization.DeserializationException`. This can happen, for example, if unexpected XML elements or XML attributes are encountered, or an expected XML element is missing. Disregarding XML Attributes @@ -161,14 +161,14 @@ Here is an example snippet: import xml.etree.ElementTree from typing import Tuple, Iterator - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( '\n' '\n' + ' xsi:schemaLocation="https://admin-shell.io/aas/3/2/AAS.xsd">\n' '\n' ) @@ -200,6 +200,6 @@ Here is an example snippet: serialization = aas_xmlization.to_str(environment) assert ( - '' + '' == serialization ) diff --git a/docs/source/index.rst b/docs/source/index.rst index e71362f..8b3c1fc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,4 +1,4 @@ -Welcome to aas-core3.1's documentation! +Welcome to aas-core3.2's documentation! ================================================== Table of Contents diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index cf715d3..dfe99fd 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -8,9 +8,9 @@ This is a software development kit (SDK) to: * verify, and * de/serialize to and from JSON and XML -... Asset Administration Shells based on `the version 3.1 of the meta-model`_. +... Asset Administration Shells based on `the version 3.2 of the meta-model`_. -.. _the version 3.1 of the meta-model: https://industrialdigitaltwin.org/content-hub/aasspecifications +.. _the version 3.2 of the meta-model: https://industrialdigitaltwin.org/content-hub/aasspecifications For a brief introduction, see :doc:`Getting Started `. diff --git a/pyproject.toml b/pyproject.toml index 6ddb14d..b848acf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,6 +28,7 @@ classifiers = [ [project.urls] Homepage = "https://github.com/eclipse-aascw/aas-core3.2-python" +Documentation = "https://eclipse-aascw.github.io/aas-core3.2-python/" Repository = "https://github.com/eclipse-aascw/aas-core3.2-python" Issues = "https://github.com/eclipse-aascw/aas-core3.2-python/issues"