From 9d0f51bd70a2fe466b164468cba127f229973e9c Mon Sep 17 00:00:00 2001 From: ewuerger Date: Thu, 16 Jan 2025 16:50:32 +0100 Subject: [PATCH] docs!: Include notebooks in documentation --- .github/workflows/docs.yml | 2 + docs/.readthedocs.yaml | 2 +- docs/Makefile | 7 +- docs/make.bat | 37 --- docs/source/conf.py | 4 + docs/source/examples/.gitignore | 10 + ...1 How to develop and debug a LiveDoc.ipynb | 223 ++++++++++++++++++ ... develop and debug a LiveDoc.ipynb.license | 2 + .../02 How to generate work-items.ipynb | 14 +- ...2 How to generate work-items.ipynb.license | 0 .../capella2polarion_document_config.yaml.j2 | 44 ++++ .../document_templates/test-classes.html.j2 | 0 .../document_templates/test-icd.html.j2 | 0 .../document_templates/test-pcd.html.j2 | 80 +++++++ .../examples}/element_templates/class.html.j2 | 0 .../element_templates/common_macros.html.j2 | 0 .../element_templates/exchange_item.html.j2 | 0 .../element_templates/polarion_props.j2 | 0 docs/source/howtos.rst | 24 ++ docs/source/index.rst | 6 + jupyter-notebooks/document_generation.ipynb | 167 ------------- .../element_generation.ipynb.license | 2 - pyproject.toml | 8 +- tests/data/documents/combined_config.yaml | 10 +- .../data/documents/full_authority_config.yaml | 4 +- tests/data/documents/mixed_config.yaml | 4 +- tests/test_documents.py | 2 +- tests/test_elements.py | 3 +- 28 files changed, 431 insertions(+), 224 deletions(-) delete mode 100644 docs/make.bat create mode 100644 docs/source/examples/.gitignore create mode 100644 docs/source/examples/01 How to develop and debug a LiveDoc.ipynb create mode 100644 docs/source/examples/01 How to develop and debug a LiveDoc.ipynb.license rename jupyter-notebooks/element_generation.ipynb => docs/source/examples/02 How to generate work-items.ipynb (95%) rename jupyter-notebooks/document_generation.ipynb.license => docs/source/examples/02 How to generate work-items.ipynb.license (100%) create mode 100644 docs/source/examples/configs/capella2polarion_document_config.yaml.j2 rename {jupyter-notebooks => docs/source/examples}/document_templates/test-classes.html.j2 (100%) rename {jupyter-notebooks => docs/source/examples}/document_templates/test-icd.html.j2 (100%) create mode 100644 docs/source/examples/document_templates/test-pcd.html.j2 rename {jupyter-notebooks => docs/source/examples}/element_templates/class.html.j2 (100%) rename {jupyter-notebooks => docs/source/examples}/element_templates/common_macros.html.j2 (100%) rename {jupyter-notebooks => docs/source/examples}/element_templates/exchange_item.html.j2 (100%) rename {jupyter-notebooks => docs/source/examples}/element_templates/polarion_props.j2 (100%) create mode 100644 docs/source/howtos.rst delete mode 100644 jupyter-notebooks/document_generation.ipynb delete mode 100644 jupyter-notebooks/element_generation.ipynb.license diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2460fa7..ab1af09 100644 --- a/.github/workflows/docs.yml +++ b/.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 diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml index 509f613..ddb25c0 100644 --- a/docs/.readthedocs.yaml +++ b/docs/.readthedocs.yaml @@ -7,7 +7,7 @@ version: 2 build: - os: ubuntu-22.04 + os: ubuntu-24.04 tools: python: "3.12" jobs: diff --git a/docs/Makefile b/docs/Makefile index 2fc871c..2f32590 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 9f24710..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,37 +0,0 @@ -@ECHO OFF -REM Copyright DB InfraGO AG and contributors -REM SPDX-License-Identifier: CC0-1.0 - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%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.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/conf.py b/docs/source/conf.py index caae991..9383917 100644 --- a/docs/source/conf.py +++ b/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 = "\\" diff --git a/docs/source/examples/.gitignore b/docs/source/examples/.gitignore new file mode 100644 index 0000000..d8a05ae --- /dev/null +++ b/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 diff --git a/docs/source/examples/01 How to develop and debug a LiveDoc.ipynb b/docs/source/examples/01 How to develop and debug a LiveDoc.ipynb new file mode 100644 index 0000000..847fdd5 --- /dev/null +++ b/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 +} diff --git a/docs/source/examples/01 How to develop and debug a LiveDoc.ipynb.license b/docs/source/examples/01 How to develop and debug a LiveDoc.ipynb.license new file mode 100644 index 0000000..62a1749 --- /dev/null +++ b/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 diff --git a/jupyter-notebooks/element_generation.ipynb b/docs/source/examples/02 How to generate work-items.ipynb similarity index 95% rename from jupyter-notebooks/element_generation.ipynb rename to docs/source/examples/02 How to generate work-items.ipynb index 172d567..8bdd39b 100644 --- a/jupyter-notebooks/element_generation.ipynb +++ b/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)" ] } ], diff --git a/jupyter-notebooks/document_generation.ipynb.license b/docs/source/examples/02 How to generate work-items.ipynb.license similarity index 100% rename from jupyter-notebooks/document_generation.ipynb.license rename to docs/source/examples/02 How to generate work-items.ipynb.license diff --git a/docs/source/examples/configs/capella2polarion_document_config.yaml.j2 b/docs/source/examples/configs/capella2polarion_document_config.yaml.j2 new file mode 100644 index 0000000..992989c --- /dev/null +++ b/docs/source/examples/configs/capella2polarion_document_config.yaml.j2 @@ -0,0 +1,44 @@ +# Copyright DB InfraGO AG and contributors +# SPDX-License-Identifier: Apache-2.0 + +full_authority: + - template_directory: jinja/document_templates + template: test-pcd.html.j2 + heading_numbering: True + work_item_layouts: + componentExchange: + fields_at_start: + - id + fields_at_end: + - context_diagram + physicalLink: + fields_at_start: + - id + physicalActor: + fields_at_start: + - id + fields_at_end: + - context_diagram + physicalComponentNode: + fields_at_start: + - id + fields_at_end: + - context_diagram + physicalComponentBehavior: + fields_at_start: + - id + fields_at_end: + - context_diagram + physicalFunction: + fields_at_start: + - id + fields_at_end: + - context_diagram + instances: + {%- for pc in model.search("PhysicalComponent") %} + - polarion_space: PC-Drafts + polarion_name: {{ pc.uuid }} + polarion_title: "{{ pc.name | safe }}" + params: + uuid: {{ pc.uuid }} + {% endfor %} diff --git a/jupyter-notebooks/document_templates/test-classes.html.j2 b/docs/source/examples/document_templates/test-classes.html.j2 similarity index 100% rename from jupyter-notebooks/document_templates/test-classes.html.j2 rename to docs/source/examples/document_templates/test-classes.html.j2 diff --git a/jupyter-notebooks/document_templates/test-icd.html.j2 b/docs/source/examples/document_templates/test-icd.html.j2 similarity index 100% rename from jupyter-notebooks/document_templates/test-icd.html.j2 rename to docs/source/examples/document_templates/test-icd.html.j2 diff --git a/docs/source/examples/document_templates/test-pcd.html.j2 b/docs/source/examples/document_templates/test-pcd.html.j2 new file mode 100644 index 0000000..9f4b865 --- /dev/null +++ b/docs/source/examples/document_templates/test-pcd.html.j2 @@ -0,0 +1,80 @@ +{# + Copyright DB InfraGO AG and contributors + SPDX-License-Identifier: Apache-2.0 +#} + +{% from 'polarion_props.j2' import table_attributes, th_attributes, td_attributes %} + +{% set table_attributes='class="polarion-Document-table" style="margin: auto;margin-left: 0px;empty-cells: show;border-collapse: collapse;max-width: 1280px;border: 1px solid #CCCCCC;" id="polarion_wiki macro name=table"' %} +{% set th_attributes='style="height: 12px;text-align: left;vertical-align: top;font-weight: bold;background-color: #F0F0F0;border: 1px solid #CCCCCC;padding: 5px;"' %} +{% set td_attributes='style="height: 12px;text-align: left;vertical-align: top;line-height: 18px;border: 1px solid #CCCCCC;padding: 5px;"' %} + +{% set physical_component = model.by_uuid(uuid) %} + +{# Template start #} +{{ heading(1, title, session) }} +{{ heading(2, "Table of Content", session) }} +
+
+ +{{ heading(2, "Context", session) }} +The context of {{ physical_component.name }} is summarized by the context diagram below: +{{ insert_work_item(physical_component, session) }} +
+ +{% set software_components = [comp for comp in physical_component.components if comp.kind == "SOFTWARE"] %} +{% if software_components %} + {{ heading(2, "Deployed software", session) }} + {{ physical_component.name }} has the following software components deployed: + {% for sw in software_components %} + {{ insert_work_item(sw, session) }} + {% endfor %} +{% endif %} +
+ +{{ heading(2, "Electrical interfaces", session) }} +All electrical interfaces of {{ physical_component.name }} are summarized by the table below: + + + + + + + + + + + {% for port in object.physical_ports %} + {% set cables = port.links %} + {% if cables %} + {% for cable in cables %} + + {% set other_port = cable.ends | reject("equalto", port) | first %} + {% if loop.first %} + + {% endif %} + + + + + {% endfor %} + {% else %} + + + + + {% endif %} + {% endfor %} + +
PortCable IDTargetTarget Port
{{ port | link_work_item }}{{ cable | link_work_item }}{{ other_port.owner | link_work_item }}{{ other_port | link_work_item }}
{{ port | link_work_item }}No cable connections planned
+
+ +{% if physical_component.allocated_functions %} +{{ heading(2, "Allocated functions", session) }} +All allocated functions of {{ physical_component.name }} are identified below: + {{ heading(3, "Allocated Functions", session) }} + {% for fnc in physical_component.allocated_functions %} + {{ insert_work_item(fnc, session) }} + {% endfor %} +
+{% endif %} diff --git a/jupyter-notebooks/element_templates/class.html.j2 b/docs/source/examples/element_templates/class.html.j2 similarity index 100% rename from jupyter-notebooks/element_templates/class.html.j2 rename to docs/source/examples/element_templates/class.html.j2 diff --git a/jupyter-notebooks/element_templates/common_macros.html.j2 b/docs/source/examples/element_templates/common_macros.html.j2 similarity index 100% rename from jupyter-notebooks/element_templates/common_macros.html.j2 rename to docs/source/examples/element_templates/common_macros.html.j2 diff --git a/jupyter-notebooks/element_templates/exchange_item.html.j2 b/docs/source/examples/element_templates/exchange_item.html.j2 similarity index 100% rename from jupyter-notebooks/element_templates/exchange_item.html.j2 rename to docs/source/examples/element_templates/exchange_item.html.j2 diff --git a/jupyter-notebooks/element_templates/polarion_props.j2 b/docs/source/examples/element_templates/polarion_props.j2 similarity index 100% rename from jupyter-notebooks/element_templates/polarion_props.j2 rename to docs/source/examples/element_templates/polarion_props.j2 diff --git a/docs/source/howtos.rst b/docs/source/howtos.rst new file mode 100644 index 0000000..55ef3d3 --- /dev/null +++ b/docs/source/howtos.rst @@ -0,0 +1,24 @@ +.. + Copyright DB InfraGO AG and contributors + SPDX-License-Identifier: Apache-2.0 + +.. + SPDX-FileCopyrightText: Copyright DB InfraGO AG + SPDX-License-Identifier: Apache-2.0 + +.. _howtos: + +******* +How Tos +******* + +In this section you can view dedicated tutorial-notebooks of key +features. + +.. toctree:: + :maxdepth: 4 + :caption: Tutorials + :numbered: + :glob: + + ../examples/* diff --git a/docs/source/index.rst b/docs/source/index.rst index afc78f8..85af835 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -74,6 +74,12 @@ how this service is configured see the :ref:`configuration page pipeline templates/gitlab +.. toctree:: + :caption: Tutorials + :titlesonly: + + howtos + .. toctree:: :maxdepth: 2 :caption: Roadmap: diff --git a/jupyter-notebooks/document_generation.ipynb b/jupyter-notebooks/document_generation.ipynb deleted file mode 100644 index e3bf188..0000000 --- a/jupyter-notebooks/document_generation.ipynb +++ /dev/null @@ -1,167 +0,0 @@ -{ - "cells": [ - { - "cell_type": "code", - "execution_count": null, - "id": "3f2aa85c-bd79-4e81-a851-c0197acfc3b3", - "metadata": {}, - "outputs": [], - "source": [ - "from capella2polarion.connectors import polarion_worker\n", - "from capella2polarion.converters import document_renderer\n", - "import dotenv\n", - "import os\n", - "import capellambse" - ] - }, - { - "cell_type": "markdown", - "id": "e3f3d9b0-6738-49e0-b1a7-75105f483ebb", - "metadata": {}, - "source": [ - "Create a `.env` file with the following values:\n", - "- MODEL_PATH\n", - "- POLARION_PROJECT\n", - "- POLARION_HOST\n", - "- POLARION_PAT" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "eedbd73e-aa06-486f-b0d4-7c0daaa9fb62", - "metadata": {}, - "outputs": [], - "source": [ - "dotenv.load_dotenv()\n", - "model = capellambse.MelodyModel(os.environ.get(\"MODEL_PATH\", \"\"))\n", - "worker = polarion_worker.CapellaPolarionWorker(\n", - " polarion_worker.PolarionWorkerParams(\n", - " os.environ.get(\"POLARION_PROJECT\", \"\"),\n", - " os.environ.get(\"POLARION_HOST\", \"\"),\n", - " os.environ.get(\"POLARION_PAT\", \"\"),\n", - " delete_work_items=False,\n", - " )\n", - ")\n", - "worker.load_polarion_work_item_map()" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "5f90a03c-15ad-40c0-8132-9073e3e5aa44", - "metadata": {}, - "outputs": [], - "source": [ - "renderer = document_renderer.DocumentRenderer(worker.polarion_data_repo, model)" - ] - }, - { - "cell_type": "markdown", - "id": "c9e3889d-063d-480f-86e8-412af898c426", - "metadata": {}, - "source": [ - "If the document, we want to render already exists in Polarion, we should request it before we re-render it." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "9366113e-6b67-46e7-9d68-44b3f2fde61d", - "metadata": {}, - "outputs": [], - "source": [ - "old_doc=worker.client.project_client.documents.get(\"_default\", \"TEST-ICD1\", fields={\"documents\":\"@all\"})" - ] - }, - { - "cell_type": "markdown", - "id": "542dd1db-2b12-410e-9588-a67b66f7db98", - "metadata": {}, - "source": [ - "In this example we want to create a document to describe an interface. The template expects the UUID of a component exchange. As we know that the document already exists in Polarion, we pass it to the renderer, to let it reuse existing heading workitems. The workitems which should be updated are returned in addition to the newly generated document." - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "09742719-766d-40ca-b344-5235dca88933", - "metadata": {}, - "outputs": [], - "source": [ - "new_doc, wis=renderer.render_document(\n", - " \"document_templates\",\n", - " \"test-icd.html.j2\",\n", - " document=old_doc,\n", - " interface=\"3d21ab4b-7bf6-428b-ba4c-a27bca4e86db\"\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "14f2799a-ba4d-4707-ad3a-36e485cd8065", - "metadata": {}, - "outputs": [], - "source": [ - "worker.client.project_client.work_items.update(wis)\n", - "worker.client.project_client.documents.update(new_doc)" - ] - }, - { - "cell_type": "markdown", - "id": "7f204e55-1d6d-4ce8-87a2-08520be45a05", - "metadata": {}, - "source": [ - "If we want to create a new document, we don't have to pass a document" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "8756d66b-25e3-48db-bee7-3d321f3d5957", - "metadata": {}, - "outputs": [], - "source": [ - "new_doc, wis=renderer.render_document(\n", - " \"document_templates\",\n", - " \"test-icd.html.j2\",\n", - " \"_default\",\n", - " \"TEST-ICD6\",\n", - " interface=\"3d21ab4b-7bf6-428b-ba4c-a27bca4e86db\"\n", - ")" - ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "140f553f-ec59-485c-8476-0694de9241f7", - "metadata": {}, - "outputs": [], - "source": [ - "worker.client.project_client.documents.create(new_doc)" - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "capella2polarion", - "language": "python", - "name": "capella2polarion" - }, - "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.11.3" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/jupyter-notebooks/element_generation.ipynb.license b/jupyter-notebooks/element_generation.ipynb.license deleted file mode 100644 index 02c8c23..0000000 --- a/jupyter-notebooks/element_generation.ipynb.license +++ /dev/null @@ -1,2 +0,0 @@ -Copyright DB InfraGO AG and contributors -SPDX-License-Identifier: Apache-2.0 diff --git a/pyproject.toml b/pyproject.toml index 14f5b64..ed62f11 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,7 +44,13 @@ Documentation = "https://dsd-dbs.github.io/capella2polarion" [project.optional-dependencies] dev = ["python-dotenv"] -docs = ["furo", "sphinx", "sphinx-copybutton", "tomli"] +docs = [ + "furo", + "nbsphinx>=0.9.5", + "sphinx>=8.1.3", + "sphinx-copybutton", + "tomli", +] test = ["pytest", "pytest-cov"] diff --git a/tests/data/documents/combined_config.yaml b/tests/data/documents/combined_config.yaml index cadd7e3..f76d503 100644 --- a/tests/data/documents/combined_config.yaml +++ b/tests/data/documents/combined_config.yaml @@ -26,7 +26,7 @@ mixed_authority: show_title: False fields_at_end: - tree_view_diagram - - template_directory: jupyter-notebooks/document_templates + - template_directory: docs/source/examples/document_templates sections: section1: test-icd.html.j2 section2: test-icd.html.j2 @@ -37,7 +37,7 @@ mixed_authority: section_params: section1: param_1: Test - - template_directory: jupyter-notebooks/document_templates + - template_directory: docs/source/examples/document_templates sections: section1: test-icd.html.j2 section2: test-icd.html.j2 @@ -53,7 +53,7 @@ mixed_authority: section1: param_1: Test full_authority: - - template_directory: jupyter-notebooks/document_templates + - template_directory: docs/source/examples/document_templates template: test-icd.html.j2 instances: - polarion_space: _default @@ -75,13 +75,13 @@ full_authority: show_title: False fields_at_end: - tree_view_diagram - - template_directory: jupyter-notebooks/document_templates + - template_directory: docs/source/examples/document_templates template: test-no-args.html.j2 heading_numbering: True instances: - polarion_space: _default polarion_name: id1238 - - template_directory: jupyter-notebooks/document_templates + - template_directory: docs/source/examples/document_templates template: test-icd.html.j2 project_id: TestProject status_allow_list: diff --git a/tests/data/documents/full_authority_config.yaml b/tests/data/documents/full_authority_config.yaml index fdbb989..8c729b2 100644 --- a/tests/data/documents/full_authority_config.yaml +++ b/tests/data/documents/full_authority_config.yaml @@ -1,7 +1,7 @@ # Copyright DB InfraGO AG and contributors # SPDX-License-Identifier: Apache-2.0 -- template_directory: jupyter-notebooks/document_templates +- template_directory: docs/source/examples/document_templates template: test-icd.html.j2 project_id: TestProject status_allow_list: @@ -17,7 +17,7 @@ polarion_name: id1234 params: interface: 3d21ab4b-7bf6-428b-ba4c-a27bca4e86db -- template_directory: jupyter-notebooks/document_templates +- template_directory: docs/source/examples/document_templates template: test-no-args.html.j2 heading_numbering: True work_item_layouts: diff --git a/tests/data/documents/mixed_config.yaml b/tests/data/documents/mixed_config.yaml index f3ca058..4ae8372 100644 --- a/tests/data/documents/mixed_config.yaml +++ b/tests/data/documents/mixed_config.yaml @@ -2,7 +2,7 @@ # SPDX-License-Identifier: Apache-2.0 mixed_authority: - - template_directory: jupyter-notebooks/document_templates + - template_directory: docs/source/examples/document_templates project_id: TestProject status_allow_list: - draft @@ -20,7 +20,7 @@ mixed_authority: polarion_name: id1234 params: interface: 3d21ab4b-7bf6-428b-ba4c-a27bca4e86db - - template_directory: jupyter-notebooks/document_templates + - template_directory: docs/source/examples/document_templates sections: section1: test-icd.html.j2 section2: test-icd.html.j2 diff --git a/tests/test_documents.py b/tests/test_documents.py index 2743b34..8cfb59d 100644 --- a/tests/test_documents.py +++ b/tests/test_documents.py @@ -22,7 +22,7 @@ ) CLASSES_TEMPLATE = "test-classes.html.j2" -JUPYTER_TEMPLATE_FOLDER = "jupyter-notebooks/document_templates" +JUPYTER_TEMPLATE_FOLDER = "docs/source/examples/document_templates" DOCUMENT_SECTIONS = TEST_DOCUMENT_ROOT / "sections" MIXED_CONFIG = TEST_DOCUMENT_ROOT / "mixed_config.yaml" FULL_AUTHORITY_CONFIG = TEST_DOCUMENT_ROOT / "full_authority_config.yaml" diff --git a/tests/test_elements.py b/tests/test_elements.py index a0f5424..ea6e2e3 100644 --- a/tests/test_elements.py +++ b/tests/test_elements.py @@ -1976,7 +1976,7 @@ def test_add_jinja_to_description(self, model: capellambse.MelodyModel): "test", { "jinja_as_description": { - "template_folder": "jupyter-notebooks/element_templates", + "template_folder": "docs/source/examples/element_templates", "template_path": "class.html.j2", } }, @@ -2154,7 +2154,6 @@ def test_read_config_tree_view_with_params( with mock.patch.object( context.ContextDiagram, "render" ) as wrapped_render: - wis = serializer.serialize_all() _ = wis[0].attachments[0].content_bytes