docs!: Include notebooks in documentation

.github/workflows/docs.yml

@@ -23,6 +23,8 @@ jobs:
           cache: pip
           cache-dependency-path: pyproject.toml
           python-version: "3.12"
+      - name: Install system-level dependencies
+        run: sudo apt-get install -y pandoc
       - name: Upgrade pip
         run: |
           python -m pip install -U pip

docs/.readthedocs.yaml

@@ -7,7 +7,7 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
     python: "3.12"
   jobs:

docs/Makefile

@@ -6,7 +6,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
@@ -23,6 +23,11 @@ apidoc:
 
 .PHONY: apidoc
 
+clean-apidoc:
+	rm -rfv source/code
+
+.PHONY: clean-apidoc
+
 html: apidoc
 
 # Catch-all target: route all unknown targets to Sphinx using the new

docs/source/conf.py

@@ -36,6 +36,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "nbsphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
@@ -66,6 +67,9 @@
     project=project, version=version
 )
 
+# -- Options for nbsphinx ----------------------------------------------------
+nbsphinx_execute = "never"
+
 # -- Options for copy-button -------------------------------------------------
 copybutton_here_doc_delimiter = "EOT"
 copybutton_line_continuation_character = "\\"

docs/source/examples/.gitignore

@@ -0,0 +1,10 @@
+# SPDX-FileCopyrightText: Copyright DB InfraGO AG
+# SPDX-License-Identifier: CC0-1.0
+
+/*
+!/.gitignore
+!/*.ipynb
+!/*.ipynb.license
+!/configs
+!/document_templates
+!/element_templates

docs/source/examples/01 How to develop and debug a LiveDoc.ipynb

@@ -0,0 +1,223 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "1a1fe414",
+   "metadata": {},
+   "source": [
+    "# How to develop and debug a Polarion LiveDoc\n",
+    "\n",
+    "Welcome to the capella2polarion notebook where local development and debugging \n",
+    "of a Polarion LiveDoc is showcased. This notebook will show you the following:\n",
+    "- How to load all current Polarion work-items into the PolarionWorker\n",
+    "- How to load all current Polarion LiveDocs under a specified space\n",
+    "- How to create and update Polarion LiveDocs under a specified space\n",
+    "\n",
+    "Before we can interact with the REST API of Polarion we need to prepare our\n",
+    "environment:\n",
+    "Create a `.env` file with the following values:\n",
+    "- POLARION_PROJECT\n",
+    "- POLARION_HOST\n",
+    "- POLARION_PAT\n",
+    "- MODEL_PATH\n",
+    "\n",
+    "First the load the Capella model with capellambse:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3e28d1c9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from capella2polarion.connectors import polarion_worker\n",
+    "from capella2polarion.converters import document_renderer, document_config\n",
+    "\n",
+    "import dotenv\n",
+    "import os\n",
+    "import capellambse\n",
+    "import pathlib\n",
+    "\n",
+    "dotenv.load_dotenv()\n",
+    "\n",
+    "test_data_path = pathlib.Path(\"../../../tests/data\")\n",
+    "\n",
+    "model = capellambse.MelodyModel(os.environ.get(\n",
+    "    \"MODEL_PATH\") or str(test_data_path / \"model/Melody Model Test.aird\")\n",
+    ")\n",
+    "worker = polarion_worker.CapellaPolarionWorker(\n",
+    "    polarion_worker.PolarionWorkerParams(\n",
+    "            os.environ.get(\"POLARION_PROJECT\") or \"\",\n",
+    "            os.environ.get(\"POLARION_HOST\") or \"\",\n",
+    "            os.environ.get(\"POLARION_PAT\") or \"\",\n",
+    "            delete_work_items=False,\n",
+    "        )\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "48ce0c1e",
+   "metadata": {},
+   "source": [
+    "## How to load all current work items from the Polarion project into the worker:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "58c646df",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "worker.load_polarion_work_item_map()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "72383c59",
+   "metadata": {},
+   "source": [
+    "Now we load all current LiveDocs under a specific space. This is configured in\n",
+    "the document config `capella2polarion_document_config.yaml`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "1ffea0f8",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "# Copyright DB InfraGO AG and contributors\n",
+      "# SPDX-License-Identifier: Apache-2.0\n",
+      "\n",
+      "full_authority:\n",
+      "  - template_directory: jinja/document_templates\n",
+      "    template: test.html.j2\n",
+      "    heading_numbering: True\n",
+      "    work_item_layouts:\n",
+      "      componentExchange:\n",
+      "        fields_at_start:\n",
+      "          - id\n",
+      "        fields_at_end:\n",
+      "          - context_diagram\n",
+      "      physicalLink:\n",
+      "        fields_at_start:\n",
+      "          - id\n",
+      "      physicalActor:\n",
+      "        fields_at_start:\n",
+      "          - id\n",
+      "      physicalComponentActor:\n",
+      "        fields_at_start:\n",
+      "          - id\n",
+      "      physicalComponentNode:\n",
+      "        fields_at_start:\n",
+      "          - id\n",
+      "      physicalComponentBehavior:\n",
+      "        fields_at_start:\n",
+      "          - id\n",
+      "      class:\n",
+      "        show_title: False\n",
+      "        fields_at_end:\n",
+      "          - tree_view\n",
+      "      exchangeItem:\n",
+      "        show_title: False\n",
+      "    instances:\n",
+      "    {%- for pc in model.search(\"PhysicalComponent\") %}\n",
+      "    {%- if pc.components %}\n",
+      "    - polarion_space: PC-Drafts\n",
+      "      polarion_name: {{ pc.uuid }}\n",
+      "      polarion_title: \"{{ pc.name | safe }}\"\n",
+      "      params:\n",
+      "        uuid: {{ pc.uuid }}\n",
+      "    {%- endif -%}\n",
+      "    {% endfor %}\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "document_rendering_config_path = pathlib.Path(\"configs/capella2polarion_document_config.yaml.j2\")\n",
+    "print(document_rendering_config_path.read_text(encoding=\"utf8\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f5271823",
+   "metadata": {},
+   "source": [
+    "If you want to know more about the features and limitations, head into the\n",
+    "documentation of the configuration for live doc rendering.\n",
+    "\n",
+    "## How to load all current Polarion LiveDocs under a specified space"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4ec7c85f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "renderer = document_renderer.DocumentRenderer(\n",
+    "    worker.polarion_data_repo,\n",
+    "    model,\n",
+    "    os.environ.get(\"POLARION_PROJECT\") or \"\",\n",
+    "    overwrite_heading_numbering=True,\n",
+    "    overwrite_layouts=True,\n",
+    ")\n",
+    "with document_rendering_config_path.open(\"r\", encoding=\"utf8\") as file:\n",
+    "    configs = document_config.read_config_file(file, model)\n",
+    "\n",
+    "documents = worker.load_polarion_documents(configs.iterate_documents())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "80c149f4",
+   "metadata": {},
+   "source": [
+    "## How to create and update Polarion LiveDocs under a specified space"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b290d1a6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "projects_document_data = renderer.render_documents(configs, documents)\n",
+    "for project, project_data in projects_document_data.items():\n",
+    "    worker.create_documents(project_data.new_docs, project)\n",
+    "    worker.update_documents(project_data.updated_docs, project)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "py312",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/source/examples/01 How to develop and debug a LiveDoc.ipynb.license

@@ -0,0 +1,2 @@
+SPDX-FileCopyrightText: Copyright DB InfraGO AG
+SPDX-License-Identifier: Apache-2.0

jupyter-notebooks/element_generation.ipynb → docs/source/examples/02 How to generate work-items.ipynb

@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "919604fe",
+   "metadata": {},
+   "source": [
+    "# How to serialize work-items"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -61,7 +69,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from capellambse.model.crosslayer import information\n",
+    "from capellambse.metamodel import information\n",
     "\n",
     "def add_class_incl_dependencies(cls: information.Class, classes: list[information.Class]):\n",
     "    if cls in classes:\n",
@@ -154,7 +162,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "worker.client.project_client.work_items.update(wis)"
+    "worker.project_client.work_items.update(wis)"
    ]
   },
   {
@@ -214,7 +222,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "worker.client.project_client.work_items.update(wis)"
+    "worker.project_client.work_items.update(wis)"
    ]
   }
  ],