Merge remote-tracking branch 'origin/master'

.gitignore

@@ -7,3 +7,5 @@ dist/
 
 *.log
 .idea
+
+docs/system.drawio

.gitlab-ci.yml

@@ -4,6 +4,7 @@ variables:
   DOCKER_DRIVER: overlay2
   DOCKER_TLS_CERTDIR: "/certs"
   DOCKER_HOST: tcp://docker:2376
+  DRAWIO_VERSION: "21.2.8"
 
 stages:
   - build
@@ -41,3 +42,29 @@ build-upload:
     - if: $CI_PIPELINE_SOURCE == "push" || $CI_COMMIT_BRANCH == "dev"
       when: manual
       allow_failure: true
+
+deploy-docs:
+  image: python:3.11
+  stage: release
+  before_script:
+    - export DISPLAY=:0
+    - add-apt-repository ppa:apandada1/xournalpp-stable && apt-get update && apt-get install xournalpp
+    - apt-get update && apt-get -y install wget curl xvfb nano libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0 libappindicator3-1 libsecret-1-0 libgbm1 desktop-file-utils libasound2 && rm -rf /var/lib/apt/lists/*
+    - wget https://github.com/jgraph/drawio-desktop/releases/download/v$DRAWIO_VERSION/drawio-amd64-$DRAWIO_VERSION.deb
+    - dpkg -i drawio-amd64-$DRAWIO_VERSION.deb
+    - rm drawio-amd64-$DRAWIO_VERSION.deb
+    - python -V
+    - echo "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi"
+  script:
+    - export DISPLAY=:0
+    - pip install -U -r requirements.txt
+    #- python3 -m sphinx docs public
+    - inv docs --output-directory=docs/public
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: $CI_COMMIT_TAG
+    - if: $CI_PIPELINE_SOURCE == "push" || $CI_COMMIT_BRANCH == "dev"
+      when: manual
+      allow_failure: true

docs/conf.py

@@ -0,0 +1,92 @@
+import os
+import sys
+import sphinx_godot_theme as sgt
+from damper import __version__
+
+sys.path.insert(0, os.path.abspath(".."))
+html_favicon = "static/images/docs_logo.svg"
+
+supported_languages = {
+    "en": "Spring Mass Damper (%s)",
+}
+extensions = [
+    # "notfound.extension",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx_rtd_theme",
+    "sphinx_search.extension",
+    "sphinx_tabs.tabs",
+    "sphinxext.opengraph",
+    "sphinxcontrib.drawio",
+    "myst_parser",
+    "sphinx_xournal",
+]
+# autosectionlabel_prefix_document = True
+sphinx_tabs_nowarn = True
+templates_path = sgt.templates_path
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "markdown",
+    ".md": "markdown",
+}
+source_encoding = sgt.source_encoding
+master_doc = "index"
+
+# https://pypi.org/project/sphinxcontrib-drawio/
+drawio_binary_path = "/usr/bin/drawio"
+drawio_headless  = True
+drawio_no_sandbox = True
+
+author = "Arkadiusz Michał Ryś"
+project = "Spring Mass Damper"
+copyright = f"2022, {author}"
+version = __version__
+release = version
+ogp_site_name = project
+
+env_tags = os.getenv("SPHINX_TAGS")
+if env_tags is not None:
+    for tag in env_tags.split(","):
+        print("Adding Sphinx tag: %s" % tag.strip())
+        tags.add(tag.strip())  # noqa: F821
+language = os.getenv("READTHEDOCS_LANGUAGE", "en")
+if language not in supported_languages.keys():
+    print("Unknown language: " + language)
+    print("Supported languages: " + ", ".join(supported_languages.keys()))
+    print("The configured language is wrong. Falling back to 'en'.")
+    language = "en"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+pygments_style = "sphinx"
+todo_include_todos = False
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "logo_only": True,
+    "collapse_navigation": False,
+}
+html_logo = "static/images/docs_logo.svg"
+html_static_path = ["static"] + sgt.html_static_path
+htmlhelp_basename = project
+html_extra_path = sgt.html_extra_path
+html_css_files = ["css/custom.css"]
+html_js_files = ["js/custom.js"]
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+html_title = supported_languages[language] % version
+html_context = {"conf_py_path": "/"}
+latex_engine = "pdflatex"
+latex_elements = {
+    "papersize": "letterpaper",
+    "pointsize": "10pt",
+    "figure_align": "htbp",
+
+    "preamble": r"""
+    \DeclareUnicodeCharacter{2610}{[   ]}
+    \DeclareUnicodeCharacter{2611}{[X]}
+    \DeclareUnicodeCharacter{251C}{|}
+    \DeclareUnicodeCharacter{2500}{-}
+    \DeclareUnicodeCharacter{2514}{|}
+    """,
+}
+latex_documents = [(master_doc, f"{project.lower().replace(' ', '_')}.tex", project, author, "manual"),]
+man_pages = [(master_doc, project, project, [author], 1)]
+texinfo_documents = [(master_doc, project, project, author, project, project, "Miscellaneous")]
+notfound_context = sgt.notfound_context

docs/diagrams.rst

@@ -0,0 +1,23 @@
+Diagrams
+--------
+
+.. drawio-figure:: ./SpringDamperFTG.drawio
+   :format: svg
+   :page-index: 1
+   :align: center
+
+   Formalism Transformation Graph for the tuning workflow of a spring-mass-damper.
+
+.. drawio-figure:: ./SpringDamperPM.drawio
+   :format: svg
+   :page-index: 1
+   :align: center
+
+   Process Model for the tuning workflow of a spring-mass-damper.
+
+.. drawio-figure:: ./system.drawio
+   :format: svg
+   :page-index: 1
+   :align: center
+
+   Causal Block Diagram for the spring-mass-damper.

docs/index.rst

@@ -0,0 +1,13 @@
+.. include:: ../README.md
+
+
+Index
+-----
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Files:
+   :name: sec-files
+
+   diagrams
+   sketch

docs/sketch.rst

@@ -0,0 +1,8 @@
+Sketch
+------
+
+.. xournal-figure:: ./springDamper.xopp
+   :format: svg
+   :align: center
+
+   Sketch of the spring-mass-damper requirements.

docs/static/images/docs_logo.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-32 -32 64 64">
+    <circle
+      cx="0"
+      cy="0"
+      r="16"
+      fill="#b35a13"
+      stroke="#000"
+      stroke-miterlimit="10"
+      stroke-width="15px"/>
+</svg>

docs/templates/layout.html

@@ -0,0 +1,5 @@
+{% extends "!layout.html" -%}
+
+{% block htmltitle -%}
+<title>{{ title|striptags|e }}{{ titlesuffix }}</title>
+{% endblock -%}

requirements.txt

@@ -5,9 +5,14 @@ matplotlib ~= 3.7.1
 # Test
 pytest ~= 7.3.1
 # Doc
-sphinx ~= 7.0.1
+sphinx               >= 5, < 8
+sphinx-tabs          ~= 3.4.1
+myst-parser          ~= 1.0.0
+sphinx-xournal       ~= 0.1.1
+sphinx-godot-theme   ~= 0.4.2
+sphinxcontrib-drawio ~= 0.0.16
 # Dev
-tox         ~= 4.5.1
+tox         ~= 4.6.0
 pip         ~= 23.1.2
 flit        ~= 3.9.0
 twine       ~= 4.0.2
@@ -15,4 +20,4 @@ vermin      ~= 1.5.1
 invoke      ~= 2.1.2
 jinja2      ~= 3.1.2
 flake8      ~= 6.0.0
-coverage    ~= 7.2.6
+coverage    ~= 7.2.7

tasks.py

@@ -12,10 +12,21 @@ def lint(c):
     c.run(f"python3 -m pylint {system}")
 
 
-@task(name="docs")
-def documentation(c):
-    """Build the documentation."""
-    c.run("python3 -m sphinx docs docs/build/html")
+@task(name="docs", aliases=("html", "documentation"))
+def docs_html(c, output_directory="build/html"):
+    """Build the documentation in HTML form."""
+    c.run(f"cp damper/system.drawio docs/system.drawio")
+    c.run(f"python3 -m sphinx docs {output_directory}")
+    if output_directory == "docs/public":
+        c.run(f"cp -r docs/public/* ./public")
+
+
+@task
+def clean(c):
+    """Remove all artefacts."""
+    patterns = ["build", "docs/build"]
+    for pattern in patterns:
+        c.run(f"rm -rf {pattern}")
 
 
 @task