Create documentation build

.gitlab-ci.yml

@@ -0,0 +1,36 @@
+image: python:3.11
+
+variables:
+  DOCKER_DRIVER: overlay2
+  DOCKER_TLS_CERTDIR: "/certs"
+  DOCKER_HOST: tcp://docker:2376
+  DRAWIO_VERSION: "21.2.8"
+
+stages:
+  - build
+  - test
+  - release
+
+deploy-docs:
+  image: python:3.11
+  stage: release
+  before_script:
+    - export DISPLAY=:0
+    - 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
+  artifacts:
+    paths:
+      - public
+  rules:
+    - if: $CI_COMMIT_TAG
+    - if: $CI_PIPELINE_SOURCE == "push" || $CI_COMMIT_BRANCH == "dev"
+      when: manual
+      allow_failure: true

docs/__init__.py

@@ -0,0 +1,3 @@
+"""DTDesign project deployment documentation."""
+__version__ = "0.0.1"
+__version_info__ = tuple((int(num) if num.isdigit() else num for num in __version__.replace("-", ".", 1).split(".")))

docs/conf.py

@@ -0,0 +1,91 @@
+import os
+import sys
+import sphinx_godot_theme as sgt
+from docs import __version__
+
+sys.path.insert(0, os.path.abspath(".."))
+html_favicon = "static/images/docs_logo.svg"
+
+supported_languages = {
+    "en": "DigitalTwin Deployment (%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",
+]
+# 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 = "DigitalTwin"
+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}.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/index.rst

@@ -0,0 +1,12 @@
+.. include:: ../README.md
+
+
+Index
+-----
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Introduction:
+   :name: sec-introduction
+
+   integration

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

@@ -0,0 +1,21 @@
+# Deployer
+
+# Test
+pytest ~= 7.3.1
+# Doc
+sphinx               ~= 7.0.1
+sphinx-tabs          ~= 3.4.1
+myst-parser          ~= 1.0.0
+sphinx-godot-theme   ~= 0.4.2
+sphinxcontrib-drawio ~= 0.0.16
+#mkdocs-material ~= 9.1.15
+# Dev
+tox         ~= 4.5.1
+pip         ~= 23.1.2
+flit        ~= 3.9.0
+twine       ~= 4.0.2
+vermin      ~= 1.5.1
+invoke      ~= 2.1.2
+jinja2      ~= 3.1.2
+flake8      ~= 6.0.0
+coverage    ~= 7.2.6

tasks.py

@@ -1,6 +1,58 @@
 from invoke import task
 
 
+@task
+def clean(c):
+    """Remove all artefacts."""
+    patterns = ["build", "docs/build"]
+    for pattern in patterns:
+        c.run(f"rm -rf {pattern}")
+
+
+@task(name="docs", aliases=("html", "documentation"))
+def docs_html(c, output_directory="build/html"):
+    """Build the documentation in HTML form."""
+    c.run(f"python3 -m sphinx docs {output_directory}")
+
+
+@task
+def release(c, version):
+    """"""
+    if version not in ["minor", "major", "patch"]:
+        print("Version can be either major, minor or patch.")
+        return
+
+    from docs import __version_info__, __version__
+    _major, _minor, _patch = __version_info__
+
+    if version == "patch":
+        _patch = _patch + 1
+    elif version == "minor":
+        _minor = _minor + 1
+        _patch = 0
+    elif version == "major":
+        _major = _major + 1
+        _minor = 0
+        _patch = 0
+
+    c.run(f"git checkout -b release-{_major}.{_minor}.{_patch} dev")
+    c.run(f"sed -i 's/{__version__}/{_major}.{_minor}.{_patch}/g' docs/__init__.py")
+    print(f"Update the readme for version {_major}.{_minor}.{_patch}.")
+    input("Press enter when ready.")
+    c.run(f"git add -u")
+    c.run(f'git commit -m "Update changelog version {_major}.{_minor}.{_patch}"')
+    c.run(f"git push --set-upstream origin release-{_major}.{_minor}.{_patch}")
+    c.run(f"git checkout main")
+    c.run(f"git merge --no-ff release-{_major}.{_minor}.{_patch}")
+    c.run(f'git tag -a {_major}.{_minor}.{_patch} -m "Release {_major}.{_minor}.{_patch}"')
+    c.run(f"git push")
+    c.run(f"git checkout dev")
+    c.run(f"git merge --no-ff release-{_major}.{_minor}.{_patch}")
+    c.run(f"git push")
+    c.run(f"git branch -d release-{_major}.{_minor}.{_patch}")
+    c.run(f"git push origin --tags")
+
+
 @task
 def local(c):
     """"""