Publish docs on GitHub Pages instead of readthedocs

.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

README.rst

@@ -17,18 +17,18 @@ 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`_.
 
 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

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__

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__

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

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__

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__

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__

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__

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__

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__

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__

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__

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__

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,

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(

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