Add v3 docs (and convenience scripts for working with docs) (#327)

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -133,3 +133,33 @@ The webpack-dev-server is now listening on [http://localhost:8888](http://localh
 npm install -g npm-check-updates
 npm run update
 ```
+
+### Building the Docs
+
+To build the docs, you need [pip installed](https://pip.pypa.io/en/stable/installation/#). You neeed to build Apollon's type definitions before you can build the docs:
+
+```bash
+npm run prepare
+```
+
+Then install necessary dependencies for the docs:
+
+```bash
+npm run docs:prepare
+```
+
+You can now build the docs:
+
+```bash
+npm run docs:build
+```
+
+The docs will be built and put into `docs/build/html`.
+
+You can also serve the docs locally:
+
+```bash
+npm run docs:watch
+```
+
+The docs will be served on `localhost:8088`. This script will also watch for changes in the docs and rebuild them automatically.

docs/requirements.txt

@@ -1,3 +1,4 @@
 Sphinx==3.0.3
 sphinx-rtd-theme==0.4.3
 sphinx-copybutton==0.3.0
+Jinja2<3.1

docs/source/conf.py

@@ -20,13 +20,13 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Apollon'
-copyright = '2022, Stephan Krusche'
+copyright = '2023, Stephan Krusche'
 author = 'Stephan Krusche'
 
 # The short X.Y version
 version = ''
 # The full version, including alpha/beta/rc tags
-release = '2.12.9'
+release = '3.3.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/index.rst

@@ -17,6 +17,7 @@ Welcome to Apollon's documentation!
 
    user/getting-started
    user/api
+   user/uml-model-helpers
 
 .. toctree::
    :caption: Contributor Guide

docs/source/user/api.rst

@@ -15,3 +15,6 @@ Types:
 
 .. literalinclude:: api/typings.d.ts
   :language: typescript
+
+It is recommended to NOT work with UML model objects directly, specifically if you need to process UML models created with older versions of Apollon. Instead, use `UMLModelCompat` type and use the :ref:`uml-model-helpers`, which provide
+backwards compatibility out of the box.

docs/source/user/api/helpers.d.ts

@@ -0,0 +1,77 @@
+import { Assessment, UMLElement, UMLRelationship } from '../typings';
+import { UMLModelCompat } from './typings';
+/**
+ *
+ * Finds an element in the model by id
+ *
+ * @param {UMLModelCompat} model the model to search
+ * @param {string} id the id of the element to find
+ * @returns {UMLElement | undefined} the element or undefined if not found
+ */
+export declare function findElement(model: UMLModelCompat, id: string): UMLElement | undefined;
+/**
+ *
+ * Adds given element to given model. If element with same id already exists, it will be replaced.
+ *
+ * @param {UMLModelCompat} model the model to update
+ * @param {UMLElement} element the element to add or update
+ */
+export declare function addOrUpdateElement(model: UMLModelCompat, element: UMLElement): void;
+/**
+ *
+ * Finds a relationship in the model by id
+ *
+ * @param {UMLModelCompat} model the model to search
+ * @param {string} id the id of the relationship to find
+ * @returns {UMLRelationship | undefined} the relationship or undefined if not found
+ */
+export declare function findRelationship(model: UMLModelCompat, id: string): UMLRelationship | undefined;
+/**
+ *
+ * Adds given relationship to given model. If relationship with same id already exists, it will be replaced.
+ *
+ * @param {UMLModelCompat} model the model to update
+ * @param {UMLRelationship} relationship the relationship to add or update
+ */
+export declare function addOrUpdateRelationship(model: UMLModelCompat, relationship: UMLRelationship): void;
+/**
+ *
+ * Finds an assessment in the model by id
+ *
+ * @param {UMLModelCompat} model the model to search
+ * @param {string} id the id of the assessment to find
+ * @returns {Assessment | undefined} the assessment or undefined if not found
+ */
+export declare function findAssessment(model: UMLModelCompat, id: string): Assessment | undefined;
+/**
+ *
+ * Adds given assessment to given model. If assessment with same id already exists, it will be replaced.
+ *
+ * @param {UMLModelCompat} model the model to update
+ * @param {Assessment} assessment the assessment to add or update
+ */
+export declare function addOrUpdateAssessment(model: UMLModelCompat, assessment: Assessment): void;
+/**
+ * @returns true if the element is interactive, false otherwise.
+ */
+export declare function isInteractiveElement(model: UMLModelCompat, id: string): boolean;
+/**
+ * Sets the interactive state of the element.
+ *
+ * @param {UMLModelCompat} model the model to update
+ * @param {string} id the id of the element to set interactive state
+ * @param {boolean} interactive the interactive state to set
+ */
+export declare function setInteractiveElement(model: UMLModelCompat, id: string, interactive: boolean): void;
+/**
+ * @returns true if the relationship is interactive, false otherwise.
+ */
+export declare function isInteractiveRelationship(model: UMLModelCompat, id: string): boolean;
+/**
+ * Sets the interactive state of the relationship.
+ *
+ * @param {UMLModelCompat} model the model to update
+ * @param {string} id the id of the relationship to set interactive state
+ * @param {boolean} interactive the interactive state to set
+ */
+export declare function setInteractiveRelationship(model: UMLModelCompat, id: string, interactive: boolean): void;

docs/source/user/uml-model-helpers.rst

@@ -0,0 +1,10 @@
+.. _uml-model-helpers:
+
+################
+UML Model Helpers
+################
+
+Use the following helper functions to read and modify UML models:
+
+.. literalinclude:: api/helpers.d.ts
+  :language: typescript