From b271a35f5c0b7e35541d0b14862b1022ca217cb2 Mon Sep 17 00:00:00 2001 From: Stephan Krusche Date: Wed, 25 Dec 2024 10:27:19 +0100 Subject: [PATCH] Development: Update docs requirements and align the settings with the latest version --- .github/workflows/build.yml | 6 +- LICENSE | 2 +- docs/.gitignore | 6 + docs/.readthedocs.yaml | 13 ++ docs/Dockerfile | 15 ++ docs/Makefile | 10 +- docs/_static/css/style.css | 6 + docs/conf.py | 81 ++++++++++ .../dev/adding-another-diagram-type.rst | 0 docs/{source => }/dev/api/diagram-type.d.ts | 0 docs/{source => }/dev/decorator_pattern.svg | 0 docs/{source => }/dev/examples.rst | 94 +++++------ docs/{source => }/dev/general-concepts.rst | 4 +- docs/{source => }/dev/model.png | Bin .../dev/realtime-collaboration-flow.svg | 0 .../dev/realtime-collaboration.rst | 16 +- docs/{source => }/dev/repository-overview.rst | 3 +- docs/{source => }/dev/setup.rst | 0 docs/{source => }/index.rst | 5 - docs/make.bat | 15 +- docs/requirements.txt | 13 +- docs/source/conf.py | 147 ------------------ docs/{source => }/user/api.rst | 0 .../{source => }/user/api/apollon-editor.d.ts | 0 docs/{source => }/user/api/helpers.d.ts | 0 docs/{source => }/user/api/typings.d.ts | 0 docs/{source => }/user/getting-started.rst | 0 .../user/realtime-collaboration.rst | 10 +- docs/{source => }/user/uml-model-helpers.rst | 6 +- package.json | 2 +- src/tests/unit/apollon-editor-test.tsx | 2 +- 31 files changed, 221 insertions(+), 235 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/.readthedocs.yaml create mode 100644 docs/Dockerfile create mode 100644 docs/_static/css/style.css create mode 100644 docs/conf.py rename docs/{source => }/dev/adding-another-diagram-type.rst (100%) rename docs/{source => }/dev/api/diagram-type.d.ts (100%) rename docs/{source => }/dev/decorator_pattern.svg (100%) rename docs/{source => }/dev/examples.rst (76%) rename docs/{source => }/dev/general-concepts.rst (99%) rename docs/{source => }/dev/model.png (100%) rename docs/{source => }/dev/realtime-collaboration-flow.svg (100%) rename docs/{source => }/dev/realtime-collaboration.rst (93%) rename docs/{source => }/dev/repository-overview.rst (99%) rename docs/{source => }/dev/setup.rst (100%) rename docs/{source => }/index.rst (73%) delete mode 100644 docs/source/conf.py rename docs/{source => }/user/api.rst (100%) rename docs/{source => }/user/api/apollon-editor.d.ts (100%) rename docs/{source => }/user/api/helpers.d.ts (100%) rename docs/{source => }/user/api/typings.d.ts (100%) rename docs/{source => }/user/getting-started.rst (100%) rename docs/{source => }/user/realtime-collaboration.rst (96%) rename docs/{source => }/user/uml-model-helpers.rst (71%) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 804dca7db..b30ca4c18 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,7 +7,7 @@ on: branches: [ develop ] env: - node: 16.x + node: 22 jobs: build: @@ -16,10 +16,10 @@ jobs: steps: - name: Setup Node.js '${{ env.node }}' - uses: actions/setup-node@v1 + uses: actions/setup-node@v4 with: node-version: '${{ env.node }}' - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - name: Cache node modules uses: actions/cache@v2 with: diff --git a/LICENSE b/LICENSE index 0c7db4946..bcc6ca180 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 TUM Applied Software Engineering +Copyright (c) 2025 TUM Applied Education Technologies Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..220f5e8dc --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,6 @@ +_build/ +.venv/ +.idea/ +__pycache__/ +.env +venv diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 000000000..332190edd --- /dev/null +++ b/docs/.readthedocs.yaml @@ -0,0 +1,13 @@ +--- +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.13" +sphinx: + fail_on_warning: true + configuration: docs/conf.py +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 000000000..f22894386 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,15 @@ +FROM sphinxdoc/sphinx + +WORKDIR /docs +# create non-root user to be able to edit the generated files without root access later +RUN groupadd -g 1000 sphinx-user \ + && useradd -ms /bin/bash -u 1000 -g 1000 sphinx-user \ + && chown 1000:1000 /docs +ADD requirements.txt /docs +RUN pip3 install -r requirements.txt + +USER sphinx-user +EXPOSE 8000 +# use the autobuild as default command +ENV SPHINXOPTS="--port 8000 --host 0.0.0.0" +CMD exec make livehtml diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf10..e7c2e9cec 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -3,15 +3,19 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= +# -W: treat warnings as errors +SPHINXOPTS ?= -W SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build +SOURCEDIR = . +BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +livehtml: + sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new diff --git a/docs/_static/css/style.css b/docs/_static/css/style.css new file mode 100644 index 000000000..d4c71e38a --- /dev/null +++ b/docs/_static/css/style.css @@ -0,0 +1,6 @@ +/* This import resolves when built */ +@import url("theme.css"); + +.wy-body-for-nav .wy-nav-content { + max-width: none; +} diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..ea58e08e9 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,81 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Apollon' +copyright = '2025, Applied Education Technologies, Technical University of Munich' +author = 'Applied Education Technologies, Technical University of Munich' + + +# -- General configuration --------------------------------------------------- + +# The document name of the “main” document, that is, the document +# that contains the root toctree directive. +master_doc = "index" + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx_rtd_theme", +] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv'] + +linkcheck_ignore = [ + r'http(s)?://.*localhost(:\d+)?/?', + r'https://Apollon.cs.hm.edu/', # DNS entry no longer exists + r'https://bamboo.ase.in.tum.de/build/admin/edit/.*', + r'https://hermes.Apollon.cit.tum.de/', # expired certificate + # IEEE server returns code 418 when checking links + r'https://doi.org/10.1109/CSEET58097.2023.00020', + r'https://doi.org/10.1109/CSEET58097.2023.00021', + r'https://doi.org/10.1109/CSEET58097.2023.00031', + r'https://doi.org/10.1109/CSEET58097.2023.00037', + r'https://doi.org/10.1109/ITHET50392.2021.9759809', +] +# do not check anchors on websites that need JavaScript to load the content +# the anchor points to +linkcheck_anchors_ignore_for_url = [ + r"https://angular.io/guide/.*", + r"https://github.com/.*", + r"https://k3d.io/.*" +] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' +html_context = { + "display_github": True, + "github_user": "ls1intum", + "github_repo": "Apollon", + "github_version": "develop", + "conf_py_path": "/docs/", +} +html_style = 'css/style.css' + +# 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". +html_static_path = ['_static'] diff --git a/docs/source/dev/adding-another-diagram-type.rst b/docs/dev/adding-another-diagram-type.rst similarity index 100% rename from docs/source/dev/adding-another-diagram-type.rst rename to docs/dev/adding-another-diagram-type.rst diff --git a/docs/source/dev/api/diagram-type.d.ts b/docs/dev/api/diagram-type.d.ts similarity index 100% rename from docs/source/dev/api/diagram-type.d.ts rename to docs/dev/api/diagram-type.d.ts diff --git a/docs/source/dev/decorator_pattern.svg b/docs/dev/decorator_pattern.svg similarity index 100% rename from docs/source/dev/decorator_pattern.svg rename to docs/dev/decorator_pattern.svg diff --git a/docs/source/dev/examples.rst b/docs/dev/examples.rst similarity index 76% rename from docs/source/dev/examples.rst rename to docs/dev/examples.rst index 817a01c14..565a6295e 100644 --- a/docs/source/dev/examples.rst +++ b/docs/dev/examples.rst @@ -1,6 +1,6 @@ -########## +######## Examples -########## +######## Example of Feature Definition of Element @@ -38,54 +38,56 @@ The representation is the defined in the corresponding component class, in our e .. code-block:: typescript - export const UMLClassifierComponent: FunctionComponent = ({ element, children }) => ( - - - - {element.stereotype ? ( - - - - {`«${element.stereotype}»`} - - = ({ element, children }) => { + const fontStyle = element.italic ? 'italic' : undefined; + const textDecoration = element.underline ? 'underline' : undefined; + const headerPath = `M 0 ${element.headerHeight} H ${element.bounds.width}`; + const dividerPath = `M 0 ${element.deviderPosition} H ${element.bounds.width}`; + + return ( + + + + {element.stereotype ? ( + + + {/* «${element.stereotype}» */} + + {/* «${element.stereotype}» */} + + + {element.name} + + + + ) : ( + + {element.name} - - - - ) : ( - - - {element.name} - - - )} - {children} - - - - - ); + + + )} + {children} + + + + + ); + }; It implements the visual representation, which always made up of svg elements. diff --git a/docs/source/dev/general-concepts.rst b/docs/dev/general-concepts.rst similarity index 99% rename from docs/source/dev/general-concepts.rst rename to docs/dev/general-concepts.rst index eb066c6c3..141cf871f 100644 --- a/docs/source/dev/general-concepts.rst +++ b/docs/dev/general-concepts.rst @@ -1,6 +1,6 @@ -################# +################ General Concepts -################# +################ The ApollonEditor is a UML modeling editor which can be used to visualize and modify UML Diagrams. It can load and diff --git a/docs/source/dev/model.png b/docs/dev/model.png similarity index 100% rename from docs/source/dev/model.png rename to docs/dev/model.png diff --git a/docs/source/dev/realtime-collaboration-flow.svg b/docs/dev/realtime-collaboration-flow.svg similarity index 100% rename from docs/source/dev/realtime-collaboration-flow.svg rename to docs/dev/realtime-collaboration-flow.svg diff --git a/docs/source/dev/realtime-collaboration.rst b/docs/dev/realtime-collaboration.rst similarity index 93% rename from docs/source/dev/realtime-collaboration.rst rename to docs/dev/realtime-collaboration.rst index a12e07bb7..dafb39b3f 100644 --- a/docs/source/dev/realtime-collaboration.rst +++ b/docs/dev/realtime-collaboration.rst @@ -1,8 +1,8 @@ -#################### +###################### Realtime Collaboration -#################### +###################### -Apollon supports realtime collaboration by tracking and emitting patches when changes happen to the diagram. The patches are in the format of `RFC 6902`_ standard (i.e. `JSON Patch`_), so that they can be applied to Apollon diagrams by cliients in different languages and in various stacks (i.e. other clients, on the server, etc.). +Apollon supports realtime collaboration by tracking and emitting patches when changes happen to the diagram. The patches are in the format of `RFC 6902`_ standard (i.e. `JSON Patch`_), so that they can be applied to Apollon diagrams by clients in different languages and in various stacks (i.e. other clients, on the server, etc.). Tracking changes happens through the `patcher service `_. This service is written in a general form and then configured for the specific case of Apollon diagrams: the core of the service is the `Patcher `_ class, which tracks changes to a given object and notifies subscribers to those changes, and allows applying patches, which might have been generated by other clients and received via the network, to said object. The `Patcher` is connected to Apollon's application state using the a `Redux Middleware`_ called `PatcherMiddleware `_, which filters all incoming actions according to a given configuration and asks the `Patcher` to check for changes when necessary, and a `Redux Reducer`_ called `PatcherReducer `_, which is responsible for applying patches to the application state using the `Patcher `_. @@ -14,9 +14,9 @@ configuration and asks the `Patcher` to check for changes when necessary, and a Flow of Realtime Collaboration in Apollon -********************** +************************* Diagram Schema Guidelines -********************** +************************* The realtime collaboration system imposes some constraints on the schema of Apollon diagrams in order to be able to properly reconcile potentially conflicting changes between clients while sticking to the standard `JSON Patch`_ format. The constraints should be considered specifically when adding new diagram types. @@ -25,7 +25,7 @@ Follow these guidelines to ensure any diagram type works properly with realtime - Use maps instead of arrays as much as possible. If you have a list of items with unique IDs, use a map with the keys set as said IDs to the each item, instead of an array. - For representing sets of unique IDs, use maps mapping IDs to boolean values (i.e. inclusion maps), instead of arrays. -Dont't do this: +Don't do this: .. code-block:: typescript @@ -58,7 +58,7 @@ In scenarios where you need to represent a list of items with an array, for exam Stuttering Prevention ********************** -The `Patcher `_ also utilises a stuttering prevention mechanism to avoid applying patches that are optimistically predicted to be redundant. To this end, the `Patch Verifier `_ class is used to sign all patches created locally and record their corresponding path in the `JSON Patch`. The client assumes that the integrating platform will resend this patch to all clients, including the one that created it, and so will ignore other incoming patches on the same path until the self-signed patch is received, as such patches would be overriden by the self-signed patch anyway. +The `Patcher `_ also utilises a stuttering prevention mechanism to avoid applying patches that are optimistically predicted to be redundant. To this end, the `Patch Verifier `_ class is used to sign all patches created locally and record their corresponding path in the `JSON Patch`. The client assumes that the integrating platform will resend this patch to all clients, including the one that created it, and so will ignore other incoming patches on the same path until the self-signed patch is received, as such patches would be overridden by the self-signed patch anyway. .. _RFC 6902: https://tools.ietf.org/html/rfc6902 .. _JSON Patch: http://jsonpatch.com/ @@ -69,4 +69,4 @@ The `Patcher `_ also utilises a stuttering prevention mechanism t .. _Patcher Compare Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/compare.ts .. _Patcher Middleware Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patcher-middleware.ts .. _Patcher Reducer Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patcher-reducer.ts -.. _Patch Verifier Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patch-verifier.ts \ No newline at end of file +.. _Patch Verifier Code: https://github.com/ls1intum/Apollon/blob/develop/src/main/services/patcher/patch-verifier.ts diff --git a/docs/source/dev/repository-overview.rst b/docs/dev/repository-overview.rst similarity index 99% rename from docs/source/dev/repository-overview.rst rename to docs/dev/repository-overview.rst index ce716c1fc..0aa6bab67 100644 --- a/docs/source/dev/repository-overview.rst +++ b/docs/dev/repository-overview.rst @@ -20,8 +20,7 @@ On the top level we have the separation between `components`, `i18n`, `packages` #. `packages` contains the code which is specific to UML diagram types. A package describes one UML diagram type (location: src/main/packages/) and has: - * a component for each UML element type available in the specific UML diagram type, which describes the appearance of the elements. (Reference example) -For example in `src/main/packages/uml-object-diagram` exists + * a component for each UML element type available in the specific UML diagram type, which describes the appearance of the elements. (Reference example) For example in `src/main/packages/uml-object-diagram` exists * uml-object-attribute diff --git a/docs/source/dev/setup.rst b/docs/dev/setup.rst similarity index 100% rename from docs/source/dev/setup.rst rename to docs/dev/setup.rst diff --git a/docs/source/index.rst b/docs/index.rst similarity index 73% rename from docs/source/index.rst rename to docs/index.rst index f4a54dea7..78db81d6b 100644 --- a/docs/source/index.rst +++ b/docs/index.rst @@ -1,8 +1,3 @@ -.. Apollon documentation master file, created by - sphinx-quickstart on Mon Sep 7 17:48:38 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Welcome to Apollon's documentation! =================================== diff --git a/docs/make.bat b/docs/make.bat index dc1312ab0..ad1d610ec 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -7,8 +7,11 @@ REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) -set SOURCEDIR=source -set BUILDDIR=build +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help +if "%1" == "livehtml" goto livehtml %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( @@ -19,15 +22,17 @@ if errorlevel 9009 ( 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/ + echo.http://sphinx-doc.org/ exit /b 1 ) -if "%1" == "" goto help - %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end +:livehtml +sphinx-autobuild %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + :help %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% diff --git a/docs/requirements.txt b/docs/requirements.txt index e540e91fa..86389092c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,10 @@ -Sphinx==6.2.1 -sphinx-rtd-theme==1.2.2 -Jinja2==3.1.4 +alabaster==1.0.0 +docutils==0.21.2 +Jinja2==3.1.5 +requests==2.32.3 +Sphinx==8.1.3 +sphinx-rtd-theme==3.0.2 +sphinx-autobuild==2024.10.3 +sphinxcontrib-bibtex==2.6.3 +urllib3==2.3.0 +zipp==3.21.0 diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 39d1ac222..000000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,147 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = 'Apollon' -copyright = '2024, Stephan Krusche' -author = 'Stephan Krusche' - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.githubpages', - "sphinx_rtd_theme", - 'sphinx_copybutton', -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['.templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = 'en' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# 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". -html_static_path = ['.static'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'Apollondoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'apollon', 'Apollon Documentation', - [author], 1) -] - -# -- Extension configuration ------------------------------------------------- - -# -- Options for intersphinx extension --------------------------------------- - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} - -# -- Options for todo extension ---------------------------------------------- - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True diff --git a/docs/source/user/api.rst b/docs/user/api.rst similarity index 100% rename from docs/source/user/api.rst rename to docs/user/api.rst diff --git a/docs/source/user/api/apollon-editor.d.ts b/docs/user/api/apollon-editor.d.ts similarity index 100% rename from docs/source/user/api/apollon-editor.d.ts rename to docs/user/api/apollon-editor.d.ts diff --git a/docs/source/user/api/helpers.d.ts b/docs/user/api/helpers.d.ts similarity index 100% rename from docs/source/user/api/helpers.d.ts rename to docs/user/api/helpers.d.ts diff --git a/docs/source/user/api/typings.d.ts b/docs/user/api/typings.d.ts similarity index 100% rename from docs/source/user/api/typings.d.ts rename to docs/user/api/typings.d.ts diff --git a/docs/source/user/getting-started.rst b/docs/user/getting-started.rst similarity index 100% rename from docs/source/user/getting-started.rst rename to docs/user/getting-started.rst diff --git a/docs/source/user/realtime-collaboration.rst b/docs/user/realtime-collaboration.rst similarity index 96% rename from docs/source/user/realtime-collaboration.rst rename to docs/user/realtime-collaboration.rst index 1c2196237..5b0f2e338 100644 --- a/docs/source/user/realtime-collaboration.rst +++ b/docs/user/realtime-collaboration.rst @@ -1,8 +1,8 @@ .. _realtime-collaboration: -################ +###################### Realtime Collaboration -################ +###################### Apollon supports realtime collaboration by emitting patches when a model is changed, and importing patches potentially emitted by other Apollon clients. Patches follow the `RFC 6902`_ standard (i.e. `JSON Patch`_), @@ -33,9 +33,9 @@ This means, if client A emits patch P1 and client B emits patch P2, both clients Apollon clients sign the patches they emit and treat receiving their own patches as confirmation that the patch has been applied and ordered with patches from other clients. They also optimize based on this assumption, to recognize when they are ahead of the rest of the clients on some part of the state: when client A applies the effects of patch P1 locally, its state is ahead until other clients have also applied patch P1, so client A can safely ignore other effects on that same part of the state (as it will get overwritten by patch P1 anyway). -================ +======================= Displaying Remote Users -================ +======================= In realtime collaboration, it can be useful to display activities of other users active in the collaboration session within the diagram editor. Apollon provides methods to display other users' selections: @@ -63,4 +63,4 @@ In realtime collaboration, it can be useful to display activities of other users ): void; .. _RFC 6902: https://tools.ietf.org/html/rfc6902 -.. _JSON Patch: http://jsonpatch.com/ \ No newline at end of file +.. _JSON Patch: http://jsonpatch.com/ diff --git a/docs/source/user/uml-model-helpers.rst b/docs/user/uml-model-helpers.rst similarity index 71% rename from docs/source/user/uml-model-helpers.rst rename to docs/user/uml-model-helpers.rst index 589bc5ba0..6bf7ef058 100644 --- a/docs/source/user/uml-model-helpers.rst +++ b/docs/user/uml-model-helpers.rst @@ -1,10 +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 \ No newline at end of file + :language: typescript diff --git a/package.json b/package.json index 3abc932b5..db65d8caf 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,7 @@ "publish:patch": "npm run prepare && npm run test && npm run docs:copy-api && npm version patch && npm publish", "publish:minor": "npm run prepare && npm run test && npm run docs:copy-api && npm version minor && npm publish", "publish:major": "npm run prepare && npm run test && npm run docs:copy-api && npm version major && npm publish", - "docs:copy-api": "cp lib/es6/apollon-editor.d.ts lib/es6/typings.d.ts lib/es6/compat/helpers.d.ts docs/source/user/api && cp lib/es6/packages/diagram-type.d.ts docs/source/dev/api", + "docs:copy-api": "cp lib/es6/apollon-editor.d.ts lib/es6/typings.d.ts lib/es6/compat/helpers.d.ts docs/source/user/api && cp lib/es6/packages/diagram-type.d.ts docs/dev/api", "docs:prepare": "npm run docs:copy-api && cd docs && pip3 install -r requirements.txt", "docs:build": "cd docs && make clean && make html", "docs:watch": "npm run docs:build && serve -p 8088 docs/build/html & chokidar \"docs/source/**/*\" \"docs/images/**/*\" -c \"npm run docs:build\"" diff --git a/src/tests/unit/apollon-editor-test.tsx b/src/tests/unit/apollon-editor-test.tsx index 636805a5b..bd4b27490 100644 --- a/src/tests/unit/apollon-editor-test.tsx +++ b/src/tests/unit/apollon-editor-test.tsx @@ -7,7 +7,7 @@ import testClassDiagram from './test-resources/class-diagram.json'; import testClassDiagramV2 from './test-resources/class-diagram-v2.json'; import testCommunicationDiagram from './test-resources/communication-diagram.json'; import testCommunicationDiagramV2 from './test-resources/communication-diagram-v2.json'; -import { Selection } from '../../../docs/source/user/api/typings'; +import { Selection } from '../../../docs/user/api/typings'; import { Assessment, UMLDiagramType, UMLModel } from '../../main'; import { getRealStore } from './test-utils/test-utils'; import { AssessmentRepository } from '../../main/services/assessment/assessment-repository';