diff --git a/sdk/.readthedocs.yaml b/sdk/.readthedocs.yaml index 7fd098a4c..a5f82966c 100644 --- a/sdk/.readthedocs.yaml +++ b/sdk/.readthedocs.yaml @@ -4,16 +4,16 @@ version: 2 build: - os: ubuntu-20.04 + os: ubuntu-24.04 tools: python: "3.10" sphinx: - configuration: docs/source/conf.py + configuration: sdk/docs/source/conf.py python: install: - method: pip - path: . + path: sdk extra_requirements: - docs diff --git a/sdk/docs/source/adapter/aasx.rst b/sdk/docs/source/adapter/aasx.rst index 17c15740d..cdbfbeff8 100644 --- a/sdk/docs/source/adapter/aasx.rst +++ b/sdk/docs/source/adapter/aasx.rst @@ -1,4 +1,6 @@ -aasx - Read and write AASX-files -================================ +Read and write AASX-Files +========================= + +.. rubric:: :mod:`basyx.aas.adapter.aasx` .. automodule:: basyx.aas.adapter.aasx diff --git a/sdk/docs/source/adapter/index.rst b/sdk/docs/source/adapter/index.rst index b615f374f..82e061ecd 100644 --- a/sdk/docs/source/adapter/index.rst +++ b/sdk/docs/source/adapter/index.rst @@ -1,5 +1,7 @@ -basyx.aas.adapter: Adapter of AAS-objects from and to different file-formats -============================================================================ +Adapter of AAS-Objects from and to different file-formats +========================================================= + +.. rubric:: :mod:`basyx.aas.adapter` .. automodule:: basyx.aas.adapter diff --git a/sdk/docs/source/adapter/json.rst b/sdk/docs/source/adapter/json.rst index 70d79f90a..8b202e559 100644 --- a/sdk/docs/source/adapter/json.rst +++ b/sdk/docs/source/adapter/json.rst @@ -1,16 +1,22 @@ -json - JSON serialization and deserialization -============================================= +JSON Serialization and Deserialization +====================================== + +.. rubric:: :mod:`basyx.aas.adapter.json` .. automodule:: basyx.aas.adapter.json -json.json_serialization: JSON serialization of AAS objects -########################################################## +JSON Serialization of AAS Objects +--------------------------------- + +.. rubric:: :mod:`basyx.aas.adapter.json.json_serialization` .. automodule:: basyx.aas.adapter.json.json_serialization -json.json_deserialization: JSON deserialization into AAS objects -################################################################ +JSON Deserialization into AAS Objects +------------------------------------- + +.. rubric:: :mod:`basyx.aas.adapter.json.json_deserialization` .. automodule:: basyx.aas.adapter.json.json_deserialization diff --git a/sdk/docs/source/adapter/xml.rst b/sdk/docs/source/adapter/xml.rst index 279f78a56..8ceb5f17c 100644 --- a/sdk/docs/source/adapter/xml.rst +++ b/sdk/docs/source/adapter/xml.rst @@ -1,17 +1,23 @@ -xml - XML serialization and deserialization -=========================================== +XML Serialization and Deserialization +===================================== + +.. rubric:: :mod:`basyx.aas.adapter.xml` .. automodule:: basyx.aas.adapter.xml -xml.xml_serialization - Serialization from AAS-objects to XML -############################################################# +Serialization from AAS-Objects to XML +------------------------------------- + +.. rubric:: :mod:`basyx.aas.adapter.xml.xml_serialization` .. automodule:: basyx.aas.adapter.xml.xml_serialization -xml.xml_deserialization - Deserialization from XML to AAS-objects -################################################################# +Deserialization from XML to AAS-Objects +--------------------------------------- + +.. rubric:: :mod:`basyx.aas.adapter.xml.xml_deserialization` .. automodule:: basyx.aas.adapter.xml.xml_deserialization diff --git a/sdk/docs/source/backend/couchdb.rst b/sdk/docs/source/backend/couchdb.rst index 69a14ed14..3142fdbae 100644 --- a/sdk/docs/source/backend/couchdb.rst +++ b/sdk/docs/source/backend/couchdb.rst @@ -1,4 +1,6 @@ -couchdb - Store and Retrieve AAS-objects in a CouchDB -===================================================== +Store and Retrieve AAS-Objects in a CouchDB +=========================================== + +.. rubric:: :mod:`basyx.aas.backend.couchdb` .. automodule:: basyx.aas.backend.couchdb diff --git a/sdk/docs/source/backend/index.rst b/sdk/docs/source/backend/index.rst index 97554b3f5..c02869092 100644 --- a/sdk/docs/source/backend/index.rst +++ b/sdk/docs/source/backend/index.rst @@ -1,5 +1,7 @@ -basyx.aas.backend - Storing and Retrieving of AAS-objects in Backends -===================================================================== +Storing and Retrieving of AAS-Objects in Backends +================================================= + +.. rubric:: :mod:`basyx.aas.backend` .. automodule:: basyx.aas.backend diff --git a/sdk/docs/source/backend/local_file.rst b/sdk/docs/source/backend/local_file.rst index 6145d58f9..605a338cc 100644 --- a/sdk/docs/source/backend/local_file.rst +++ b/sdk/docs/source/backend/local_file.rst @@ -1,4 +1,6 @@ -local_file - Store and Retrieve AAS-objects as JSON Files -========================================================= +Store and Retrieve AAS-Objects as JSON Files +============================================ + +.. rubric:: :mod:`basyx.aas.backend.local_file` .. automodule:: basyx.aas.backend.local_file diff --git a/sdk/docs/source/conf.py b/sdk/docs/source/conf.py index 12fbc3059..56cdd0bd8 100644 --- a/sdk/docs/source/conf.py +++ b/sdk/docs/source/conf.py @@ -52,8 +52,17 @@ # Don't prepend the name of the current module to all classes. add_module_names = False -# Include all public documented and undocumented members by default. -autodoc_default_options = {"members": True, "undoc-members": True} +# Keep class members (methods, attributes) OUT of the global TOC / sidebar. +# Still render on the page just dont clutter / leak into navigation or TOC. +toc_object_entries = False + +# Autodoc defaults: document all public members, including undocumented +# ones (they are referenced elsewhere), and preserve source order +autodoc_default_options = { + "members": True, + "member-order": "bysource", # alphabetic ordering can break logical grouping of source files + "undoc-members": True, +} # Mapping for correctly linking other module documentations. intersphinx_mapping = { @@ -83,6 +92,12 @@ def setup(app): # html_theme = "sphinx_rtd_theme" +html_theme_options = { + "collapse_navigation": True, # collapse inactive sections (otherwise navbar can get cluttered fast) + "navigation_depth": 4, # base and xml use H2 + "titles_only": False, +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/sdk/docs/source/constraints.rst b/sdk/docs/source/constraints.rst index 24157c56f..2040a7d3e 100644 --- a/sdk/docs/source/constraints.rst +++ b/sdk/docs/source/constraints.rst @@ -37,7 +37,7 @@ an :class:`~basyx.aas.model.base.AASConstraintViolation` will be raised .. |aasd119| replace:: If any ``Qualifier/kind`` value of a ``Qualifiable/qualifier`` is equal to ``TemplateQualifier`` and the qualified element inherits from ``HasKind``, the qualified element shall be of kind ``Template`` (``HasKind/kind = Template``). .. |aasd121| replace:: For ``References``, the value of ``Key/type`` of the first ``key`` of ``Reference/keys`` shall be one of ``GloballyIdentifiables``. .. |aasd122| replace:: For external references, i.e. ``References`` with ``Reference/type = ExternalReference``, the value of ``Key/type`` of the first key of ``Reference/keys`` shall be one of ``GenericGloballyIdentifiables``. -.. |aasd123| replace:: For model references, i.e. ``References`` with ``Reference/type = ModellReference``, the value of ``Key/type`` of the first ``key`` of ``Reference/keys`` shall be one of ``AasIdentifiables``. +.. |aasd123| replace:: For model references, i.e. ``References`` with ``Reference/type = ModelReference``, the value of ``Key/type`` of the first ``key`` of ``Reference/keys`` shall be one of ``AasIdentifiables``. .. |aasd124| replace:: For external references, i.e. ``References`` with ``Reference/type = ExternalReference``, the last ``key`` of ``Reference/keys`` shall be either one of ``GenericGloballyIdentifiables`` or one of ``GenericFragmentKeys``. .. |aasd125| replace:: For model references, i.e. ``References`` with ``Reference/type`` = ``ModelReference`` with more than one key in ``Reference/keys,`` the value of ``Key/type`` of each of the keys following the first key of ``Reference/keys`` shall be one of ``FragmentKeys``. .. |aasd126| replace:: For model references, i.e. ``References`` with ``Reference/type = ModelReference`` with more than one key in ``Reference/keys,`` the value of ``Key/type`` of the last ``Key`` in the reference key chain may be one of ``GenericFragmentKeys`` or no key at all shall have a value out of ``GenericFragmentKeys``. diff --git a/sdk/docs/source/examples/_helper.rst b/sdk/docs/source/examples/_helper.rst index bbcb688e8..ed0e4a424 100644 --- a/sdk/docs/source/examples/_helper.rst +++ b/sdk/docs/source/examples/_helper.rst @@ -1,4 +1,3 @@ -data._helper - Helper Classes for AAS Class Comparison -====================================================== +:orphan: .. automodule:: basyx.aas.examples.data._helper diff --git a/sdk/docs/source/examples/example_aas.rst b/sdk/docs/source/examples/example_aas.rst index 9fa40589e..20f5e6b02 100644 --- a/sdk/docs/source/examples/example_aas.rst +++ b/sdk/docs/source/examples/example_aas.rst @@ -1,4 +1,6 @@ -data.example_aas - Create an example model.AssetAdministrationShell object -========================================================================== +Create an Example model.AssetAdministrationShell Object +======================================================= + +.. rubric:: :mod:`basyx.aas.examples.data.example_aas` .. automodule:: basyx.aas.examples.data.example_aas diff --git a/sdk/docs/source/examples/example_aas_mandatory_attributes.rst b/sdk/docs/source/examples/example_aas_mandatory_attributes.rst index c0f66a8b9..0ba812161 100644 --- a/sdk/docs/source/examples/example_aas_mandatory_attributes.rst +++ b/sdk/docs/source/examples/example_aas_mandatory_attributes.rst @@ -1,4 +1,6 @@ -data.example_aas_mandatory_attributes - AAS-objects that only contain mandatory attributes -========================================================================================== +AAS-Objects That Only Contain Mandatory Attributes +================================================== + +.. rubric:: :mod:`basyx.aas.examples.data.example_aas_mandatory_attributes` .. automodule:: basyx.aas.examples.data.example_aas_mandatory_attributes diff --git a/sdk/docs/source/examples/example_aas_missing_attributes.rst b/sdk/docs/source/examples/example_aas_missing_attributes.rst index 035e02884..fd7716317 100644 --- a/sdk/docs/source/examples/example_aas_missing_attributes.rst +++ b/sdk/docs/source/examples/example_aas_missing_attributes.rst @@ -1,4 +1,6 @@ -data.example_aas_missing_attributes - AAS-objects containing non-mandatory attributes -===================================================================================== +AAS-Objects Containing Non-Mandatory Attributes +=============================================== + +.. rubric:: :mod:`basyx.aas.examples.data.example_aas_missing_attributes` .. automodule:: basyx.aas.examples.data.example_aas_missing_attributes diff --git a/sdk/docs/source/examples/example_submodel_template.rst b/sdk/docs/source/examples/example_submodel_template.rst index b01834b6f..2aa456fbf 100644 --- a/sdk/docs/source/examples/example_submodel_template.rst +++ b/sdk/docs/source/examples/example_submodel_template.rst @@ -1,4 +1,6 @@ -data.example_submodel_template - Create an Example Submodel Template -==================================================================== +Create an Example Submodel Template +=================================== + +.. rubric:: :mod:`basyx.aas.examples.data.example_submodel_template` .. automodule:: basyx.aas.examples.data.example_submodel_template diff --git a/sdk/docs/source/examples/index.rst b/sdk/docs/source/examples/index.rst index 48aeed506..37de6706a 100644 --- a/sdk/docs/source/examples/index.rst +++ b/sdk/docs/source/examples/index.rst @@ -1,12 +1,10 @@ -basyx.aas.examples - Example classes -==================================== +Example classes +=============== .. toctree:: - :maxdepth: 2 - :caption: Contents: + :maxdepth: 1 example_aas example_aas_mandatory_attributes example_aas_missing_attributes example_submodel_template - _helper diff --git a/sdk/docs/source/index.rst b/sdk/docs/source/index.rst index 801f0750c..a5f192bf6 100644 --- a/sdk/docs/source/index.rst +++ b/sdk/docs/source/index.rst @@ -1,27 +1,25 @@ -.. Eclipse BaSyx Python SDK documentation master file, created by - sphinx-quickstart on Tue Nov 10 15:09:27 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to the Eclipse BaSyx Python SDK's documentation! ======================================================== .. toctree:: - :numbered: + :caption: User Guide :maxdepth: 2 - :caption: Contents: tutorials/index + examples/index + +.. toctree:: + :caption: API Reference + :maxdepth: 2 + model/index adapter/index backend/index - examples/index util/index constraints - -Indices and tables -================== +Indices +======= * :ref:`genindex` * :ref:`modindex` diff --git a/sdk/docs/source/model/_string_constraints.rst b/sdk/docs/source/model/_string_constraints.rst index c67df5543..3755ade42 100644 --- a/sdk/docs/source/model/_string_constraints.rst +++ b/sdk/docs/source/model/_string_constraints.rst @@ -1,5 +1,4 @@ -_string_constraints - Constraint Functions for Constrained String Types -======================================================================= +:orphan: .. automodule:: basyx.aas.model._string_constraints diff --git a/sdk/docs/source/model/aas.rst b/sdk/docs/source/model/aas.rst index a74b09c0e..2031ea005 100644 --- a/sdk/docs/source/model/aas.rst +++ b/sdk/docs/source/model/aas.rst @@ -1,4 +1,6 @@ -aas - High-level structures -=========================== +High-Level Structures +===================== + +.. rubric:: :mod:`basyx.aas.model.aas` .. automodule:: basyx.aas.model.aas diff --git a/sdk/docs/source/model/base.rst b/sdk/docs/source/model/base.rst index 6aee11c71..2d6b2f7d9 100644 --- a/sdk/docs/source/model/base.rst +++ b/sdk/docs/source/model/base.rst @@ -1,5 +1,7 @@ -base - Abstract Classes and Basic Structures -============================================ +Abstract Classes and Basic Structures +===================================== + +.. rubric:: :mod:`basyx.aas.model.base` .. automodule:: basyx.aas.model.base :exclude-members: ConstrainedList, LangStringSet diff --git a/sdk/docs/source/model/concept.rst b/sdk/docs/source/model/concept.rst index d8f9a4564..34d3b9c81 100644 --- a/sdk/docs/source/model/concept.rst +++ b/sdk/docs/source/model/concept.rst @@ -1,4 +1,6 @@ -concept - ConceptDescription and Dictionary -=========================================== +ConceptDescription and Dictionary +================================= + +.. rubric:: :mod:`basyx.aas.model.concept` .. automodule:: basyx.aas.model.concept diff --git a/sdk/docs/source/model/datatypes.rst b/sdk/docs/source/model/datatypes.rst index 50722e8ff..e1d9e07ac 100644 --- a/sdk/docs/source/model/datatypes.rst +++ b/sdk/docs/source/model/datatypes.rst @@ -1,4 +1,6 @@ -datatypes - Native Python Datatypes for Simple XSD-types -======================================================== +Native Python Datatypes for Simple XSD-Types +============================================ + +.. rubric:: :mod:`basyx.aas.model.datatypes` .. automodule:: basyx.aas.model.datatypes diff --git a/sdk/docs/source/model/index.rst b/sdk/docs/source/model/index.rst index fbd52b7d3..57d5842c4 100644 --- a/sdk/docs/source/model/index.rst +++ b/sdk/docs/source/model/index.rst @@ -1,21 +1,21 @@ -basyx.aas.model - Python Model of the AssetAdministrationShell Metamodel -======================================================================== +Python Model of the AssetAdministrationShell Metamodel +====================================================== + +.. rubric:: :mod:`basyx.aas.model` .. automodule:: basyx.aas.model .. note:: Since the Class-Attributes usually have the same names as the ``__init__``-constructor parameters, you can assume that you can use the attribute names listed in the documentation for - initiating the class. If there is discrepancy between the two, it should be stated so. + initiating the class. If there is a discrepancy between the two, it should be stated so. .. toctree:: :maxdepth: 2 - :caption: Contents: aas + submodel base concept datatypes provider - submodel - _string_constraints diff --git a/sdk/docs/source/model/provider.rst b/sdk/docs/source/model/provider.rst index e245f5523..925c1faa8 100644 --- a/sdk/docs/source/model/provider.rst +++ b/sdk/docs/source/model/provider.rst @@ -1,5 +1,7 @@ -provider - Providers for storing and retrieving AAS-objects -=========================================================== +Providers for Storing and Retrieving AAS-Objects +================================================ + +.. rubric:: :mod:`basyx.aas.model.provider` .. automodule:: basyx.aas.model.provider diff --git a/sdk/docs/source/model/submodel.rst b/sdk/docs/source/model/submodel.rst index d98a3a43c..864b57da4 100644 --- a/sdk/docs/source/model/submodel.rst +++ b/sdk/docs/source/model/submodel.rst @@ -1,5 +1,7 @@ -submodel - metamodel of the submodels and events -================================================= +Metamodel of the Submodels and Events +===================================== + +.. rubric:: :mod:`basyx.aas.model.submodel` .. automodule:: basyx.aas.model.submodel diff --git a/sdk/docs/source/tutorials/index.rst b/sdk/docs/source/tutorials/index.rst index 24f0282ab..16bc5b744 100644 --- a/sdk/docs/source/tutorials/index.rst +++ b/sdk/docs/source/tutorials/index.rst @@ -1,9 +1,10 @@ -Tutorials for working with the Eclipse BaSyx Python SDK -======================================================= +Tutorials +========= +Tutorials for working with the Eclipse BaSyx Python SDK .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :caption: Contents: tutorial_create_simple_aas diff --git a/sdk/docs/source/tutorials/tutorial_aasx.rst b/sdk/docs/source/tutorials/tutorial_aasx.rst index cd4119cd9..2937b3bb9 100644 --- a/sdk/docs/source/tutorials/tutorial_aasx.rst +++ b/sdk/docs/source/tutorials/tutorial_aasx.rst @@ -1,5 +1,5 @@ -Tutorial: AASX -============================= +Read and write AASX packages +============================ .. _tutorial_aasx: diff --git a/sdk/docs/source/tutorials/tutorial_backend_couchdb.rst b/sdk/docs/source/tutorials/tutorial_backend_couchdb.rst index e9c67743d..7cdfede64 100644 --- a/sdk/docs/source/tutorials/tutorial_backend_couchdb.rst +++ b/sdk/docs/source/tutorials/tutorial_backend_couchdb.rst @@ -1,5 +1,5 @@ -Tutorial: Backend Couchdb -============================= +Use the CouchDB backend +======================= .. _tutorial_backend_couchdb: diff --git a/sdk/docs/source/tutorials/tutorial_create_simple_aas.rst b/sdk/docs/source/tutorials/tutorial_create_simple_aas.rst index 1cba16388..de0b541bc 100644 --- a/sdk/docs/source/tutorials/tutorial_create_simple_aas.rst +++ b/sdk/docs/source/tutorials/tutorial_create_simple_aas.rst @@ -1,5 +1,5 @@ -Tutorial: Create a Simple AAS -============================= +Create a simple AAS +=================== .. _tutorial_create_simple_aas: diff --git a/sdk/docs/source/tutorials/tutorial_navigate_aas.rst b/sdk/docs/source/tutorials/tutorial_navigate_aas.rst index 57c6a935b..3d0eb907d 100644 --- a/sdk/docs/source/tutorials/tutorial_navigate_aas.rst +++ b/sdk/docs/source/tutorials/tutorial_navigate_aas.rst @@ -1,5 +1,5 @@ -Tutorial: Navigate Submodels -============================ +Navigate submodels +================== .. _tutorial_navigate_aas: diff --git a/sdk/docs/source/tutorials/tutorial_serialization_deserialization.rst b/sdk/docs/source/tutorials/tutorial_serialization_deserialization.rst index 75a5a8c67..84069b451 100644 --- a/sdk/docs/source/tutorials/tutorial_serialization_deserialization.rst +++ b/sdk/docs/source/tutorials/tutorial_serialization_deserialization.rst @@ -1,5 +1,5 @@ -Tutorial: Serialization Deserialization -======================================= +Serialize and deserialize AAS objects +===================================== .. _tutorial_serialization_deserialization: diff --git a/sdk/docs/source/tutorials/tutorial_storage.rst b/sdk/docs/source/tutorials/tutorial_storage.rst index f2c85785e..3b00f7b16 100644 --- a/sdk/docs/source/tutorials/tutorial_storage.rst +++ b/sdk/docs/source/tutorials/tutorial_storage.rst @@ -1,5 +1,5 @@ -Tutorial: Storage -================= +Store and retrieve AAS objects +============================== .. _tutorial_storage: diff --git a/sdk/docs/source/util/identification.rst b/sdk/docs/source/util/identification.rst index 1cd21863f..6dc73f988 100644 --- a/sdk/docs/source/util/identification.rst +++ b/sdk/docs/source/util/identification.rst @@ -1,4 +1,6 @@ -identification - Generate Identifiers -===================================== +Generate Identifiers +==================== + +.. rubric:: :mod:`basyx.aas.util.identification` .. automodule:: basyx.aas.util.identification diff --git a/sdk/docs/source/util/index.rst b/sdk/docs/source/util/index.rst index 4da264a09..5351c72b8 100644 --- a/sdk/docs/source/util/index.rst +++ b/sdk/docs/source/util/index.rst @@ -1,5 +1,7 @@ -basyx.aas.util - Provide helpful utilities -========================================== +Provide Helpful Utilities +========================= + +.. rubric:: :mod:`basyx.aas.util` .. automodule:: basyx.aas.util diff --git a/sdk/docs/source/util/traversal.rst b/sdk/docs/source/util/traversal.rst index 0645f8639..235b4b87d 100644 --- a/sdk/docs/source/util/traversal.rst +++ b/sdk/docs/source/util/traversal.rst @@ -1,5 +1,6 @@ -traversal - Functions for Traversing AAS Object structures -========================================================== +Functions for Traversing AAS Object Structures +============================================== +.. rubric:: :mod:`basyx.aas.util.traversal` .. automodule:: basyx.aas.util.traversal