Add documentation

.github/workflows/documentation.yaml

@@ -0,0 +1,14 @@
+---
+name: 'Documentation'
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - master
+  workflow_dispatch: {} # Allow running this workflow manually (Actions tab)
+
+jobs:
+  documentation:
+    uses: metaborg/actions/.github/workflows/mkdocs-material.yaml@main
+    with:
+      docs-dir: 'docs'

README.md

@@ -2,49 +2,18 @@
 [![Build][github-build-badge]][github-build]
 [![License][license-badge]][license]
 [![GitHub Release][github-release-badge]][github-release]
+[![Documentation][documentation-badge]][documentation]
 
 This repository contains projects for managing Spoofax 3 dependencies.
 
+[![Documentation][documentation-button]][documentation]
+
 | Artifact                          | Latest Release                                                                |
 | --------------------------------- | ----------------------------------------------------------------------------- |
 | `org.metaborg.spoofax3:platform`  | [![org.metaborg.spoofax3:platform][platform-maven-badge]][platform-maven]     |
 | `org.metaborg.spoofax3:catalog`   | [![org.metaborg.spoofax3:catalog][catalog-maven-badge]][catalog-maven]        |
 
 
-
-## Platform
-The Spoofax 3 platform specifies the versions of Spoofax dependencies that are known to work together. The `org.metaborg.spoofax3:platform` package is meant to be used by consumers of Spoofax 3 dependencies. To depend on this platform, specify in your `build.gradle.kts`:
-
-```kotlin
-repositories {
-    maven("https://artifacts.metaborg.org/content/groups/public/")
-}
-
-dependencies {
-    implementation(platform("org.metaborg.spoofax3:platform:<version>"))
-}
-```
-
-
-## Catalog
-The Spoofax 3 catalog specifies the versions of dependencies within the projects that constitute Spoofax 3 itself.
-The `org.metaborg.spoofax3:catalog` package is meant to be used internally within Spoofax 3 projects. To use this catalog, specify in your `settings.gradle.kts`:
-
-```kotlin
-dependencyResolutionManagement {
-    repositories {
-        maven("https://artifacts.metaborg.org/content/groups/public/")
-    }
-    versionCatalogs {
-        create("libs") {
-            from("org.metaborg.spoofax3:catalog:<version>")
-        }
-    }
-}
-```
-
-
-
 ## License
 Copyright 2019-2024 Delft University of Technology
 
@@ -60,6 +29,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 [license]: https://github.com/metaborg/spoofax3-depman/blob/main/LICENSE
 [github-release-badge]: https://img.shields.io/github/v/release/metaborg/spoofax3-depman
 [github-release]: https://github.com/metaborg/spoofax3-depman/releases
+[documentation-badge]: https://img.shields.io/badge/docs-latest-brightgreen
+[documentation]: https://spoofax.dev/spoofax3-depman/
+[documentation-button]: https://img.shields.io/badge/Documentation-blue?style=for-the-badge&logo=googledocs&logoColor=white
 
 [platform-maven-badge]: https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fartifacts.metaborg.org%2Fcontent%2Frepositories%2Freleases%2Forg%2Fmetaborg%2Fspoofax3%2Fplatform%2Fmaven-metadata.xml
 [platform-maven]: https://artifacts.metaborg.org/#nexus-search;gav~org.metaborg.spoofax3~platform~~~

docs/.dockerignore

@@ -0,0 +1 @@
+/.github/

docs/Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.12-alpine
+
+ARG DOCS=docs/
+ARG PORT=8000
+ARG TOOLS=tools/
+ARG REQUIREMENTS=requirements.txt
+
+RUN apk upgrade --update-cache -a \
+ && apk add --no-cache \
+      git \
+      git-fast-import \
+      openssh \
+ && apk add --no-cache --virtual .build gcc musl-dev
+
+COPY ${TOOLS} tools/
+COPY ${REQUIREMENTS} requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt \
+ && apk del .build gcc musl-dev \
+ && rm -rf /tmp/* /root/.cache
+RUN <<FILE cat > /root/.gitconfig
+[safe]
+     directory = /repo
+FILE
+
+WORKDIR /repo/${DOCS}
+EXPOSE ${PORT}
+ENTRYPOINT ["mkdocs"]
+CMD ["serve", "--dev-addr=0.0.0.0:${PORT}"]

docs/Makefile

@@ -0,0 +1,16 @@
+DIR := $(patsubst %/,%,$(dir $(abspath $(lastword ${MAKEFILE_LIST}))))
+
+# The path to the root of the Git repo
+ROOT         ?= ${DIR}/..
+# The path to the mkdocs.yml file, relative to ${ROOT}
+DOCS         ?= docs/
+# The path to the Dockerfile
+DOCKERFILE   ?= ${ROOT}/${DOCS}/Dockerfile
+# The port on which to serve the documentation on localhost
+PORT         ?= 8000
+# The path to the tools/ directory, relative to ${DOCS}
+TOOLS        ?= tools/
+# The path to the requirements.txt file, relative to ${DOCS}
+REQUIREMENTS ?= requirements.txt
+# The path where Makefile.inc lives
+include ${DIR}/Makefile.inc

docs/Makefile.inc

@@ -0,0 +1,56 @@
+# SSH Agent Socket
+ifeq (${OS},Windows_NT)         # WSL2 (Windows)
+    SSH_AGENT_SOCK := ${SSH_AUTH_SOCK}
+else
+    UNAME_S := $(shell uname -s)
+    ifeq (${UNAME_S},Darwin)    # macOS
+        SSH_AGENT_SOCK := /run/host-services/ssh-auth.sock
+    else                        # Linux
+        SSH_AGENT_SOCK := ${SSH_AUTH_SOCK}
+    endif
+endif
+
+# Builds the Docker image and outputs the hash of the built image
+DOCKER_BUILD_CMD := docker build --quiet \
+  --build-arg DOCS=${DOCS} \
+  --build-arg PORT=${PORT} \
+  --build-arg TOOLS=${TOOLS} \
+  --build-arg REQUIREMENTS=${REQUIREMENTS} \
+  --file ${DOCKERFILE} \
+  ${ROOT}/${DOCS} | head -n 1
+# Runs Docker with the specified image,
+#   mounting the Git root directory
+#   mounting the known_hosts (for GitHub authentication)
+#   mounting the SSH agent socket (for GitHub authentication)
+DOCKER_BASE_CMD := docker run --rm -it -p ${PORT}:${PORT} \
+  -v ${ROOT}:/repo:ro \
+  -v ~/.ssh/known_hosts:/root/.ssh/known_hosts:ro \
+  -v ${SSH_AGENT_SOCK}:/ssh-agent:ro --env SSH_AUTH_SOCK=/ssh-agent \
+  $(or $(shell ${DOCKER_BUILD_CMD}), $(error "Command failed: ${DOCKER_BUILD_CMD}"))
+
+# Serve the docs at <http://localhost:8000/> (default)
+serve: ${DOCKERFILE}
+	${DOCKER_BASE_CMD} serve --dev-addr=0.0.0.0:${PORT}
+
+# Builds the docs
+build: ${DOCKERFILE}
+	${DOCKER_BASE_CMD} build
+
+# Deploys the docs
+gh-deploy: ${DOCKERFILE}
+	${DOCKER_BASE_CMD} gh-deploy --force
+
+# Print version
+version: ${DOCKERFILE}
+	${DOCKER_BASE_CMD} --version
+
+# Print help
+help: ${DOCKERFILE}
+	${DOCKER_BASE_CMD} --help
+
+# Builds the image and prints its hash
+build-image: ${DOCKERFILE}
+	echo $(shell ${DOCKER_BUILD_CMD})
+
+.PHONY: serve new build deploy help build-image
+.SILENT:

docs/content/assets/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise()
+})

docs/content/assets/styles.css

@@ -0,0 +1,30 @@
+.no-ligatures code, code.no-ligatures {
+    font-variant-ligatures: none;
+}
+
+.guilabel {
+    border: 1px solid var(--md-accent-fg-color);
+    background: var(--md-code-bg-color);
+    font-size: 80%;
+    font-weight: 700;
+    border-radius: 4px;
+    padding: 1px 3px;
+    margin: auto 1px;
+}
+
+.true {
+    color: #00c853;
+}
+.trace {
+}
+.debug {
+}
+.info {
+    color: #00b8d4;
+}
+.warning {
+    color: #ff9100;
+}
+.error, .stop, .false {
+    color: #ff1744;
+}

docs/content/index.md

@@ -0,0 +1,38 @@
+---
+title: "Depman"
+---
+# Dependency Management
+This project manages the Spoofax 3 dependencies in the various Spoofax 3 projects and users of Spoofax 3 projects.
+
+
+
+## Platform
+The Spoofax 3 platform specifies the versions of Spoofax dependencies that are known to work together. The `org.metaborg.spoofax3:platform` package is meant to be used by consumers of Spoofax 3 dependencies. To depend on this platform, specify in your `build.gradle.kts`:
+
+```kotlin
+repositories {
+    maven("https://artifacts.metaborg.org/content/groups/public/")
+}
+
+dependencies {
+    implementation(platform("org.metaborg.spoofax3:platform:<version>"))
+}
+```
+
+
+## Catalog
+The Spoofax 3 catalog specifies the versions of dependencies within the projects that constitute Spoofax 3 itself.
+The `org.metaborg.spoofax3:catalog` package is meant to be used internally within Spoofax 3 projects. To use this catalog, specify in your `settings.gradle.kts`:
+
+```kotlin
+dependencyResolutionManagement {
+    repositories {
+        maven("https://artifacts.metaborg.org/content/groups/public/")
+    }
+    versionCatalogs {
+        create("libs") {
+            from("org.metaborg.spoofax3:catalog:<version>")
+        }
+    }
+}
+```

docs/mkdocs.yml

@@ -0,0 +1,99 @@
+---
+# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+site_name: Gitonium
+site_description: A plugin for version management using Git
+site_author: Delft University of Technology
+
+docs_dir: content/
+repo_url: https://github.com/metaborg/gitonium
+edit_uri: https://github.com/metaborg/gitonium/edit/main/docs
+
+nav:
+  - Home:
+      - index.md
+
+theme:
+  name: material
+  language: en
+  icon:
+    logo: fontawesome/solid/code-fork
+    repo: fontawesome/brands/github
+  palette:
+    # Light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: deep purple
+      accent: orange
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    # Dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: deep purple
+      accent: orange
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  font:
+    code: "JetBrains Mono"
+  features:
+    - navigation.tabs
+    - navigation.top
+    - navigation.indexes
+    - content.code.annotate
+
+extra_css:
+  - assets/styles.css
+extra_javascript:
+  - assets/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.highlight:
+      guess_lang: false
+  - pymdownx.inlinehilite:
+      custom_inline:
+        - name: gui
+          class: guilabel
+          format: !!python/name:formatters.inline_span_format
+  - pymdownx.keys:
+      key_map:
+        click: "Click"
+        left-click: "Left Click"
+        right-click: "Right Click"
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.saneheaders
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+plugins:
+  - search
+  - git-revision-date-localized:
+      enable_creation_date: true
+      fallback_to_build_date: true
+  - macros:
+      module_name: tools/macro

docs/requirements.txt

@@ -0,0 +1,5 @@
+mkdocs==1.6.0
+mkdocs-material==9.5.28
+mkdocs-macros-plugin==1.0.5
+mkdocs-git-revision-date-localized-plugin==1.2.6
+./tools/

docs/tools/__init__.py

@@ -0,0 +1 @@
+"""Tools"""

docs/tools/formatters.py

@@ -0,0 +1,8 @@
+from markdown import util as md_util
+import xml.etree.ElementTree as etree
+
+def inline_span_format(source="", language="gui", class_name="guilabel", md=None):
+    """Inline generic span formatter."""
+    el = etree.Element('span', {'class': class_name})
+    el.text = md_util.AtomicString(source.replace(">", "‣"))
+    return el