diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml new file mode 100644 index 0000000..77c365c --- /dev/null +++ b/.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' diff --git a/README.md b/README.md index 2fe4fda..c89659a 100644 --- a/README.md +++ b/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:")) -} -``` - - -## 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:") - } - } -} -``` - - - ## 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~~~ diff --git a/docs/.dockerignore b/docs/.dockerignore new file mode 100644 index 0000000..0f7f543 --- /dev/null +++ b/docs/.dockerignore @@ -0,0 +1 @@ +/.github/ diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 0000000..1e4fed0 --- /dev/null +++ b/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 < /root/.gitconfig +[safe] + directory = /repo +FILE + +WORKDIR /repo/${DOCS} +EXPOSE ${PORT} +ENTRYPOINT ["mkdocs"] +CMD ["serve", "--dev-addr=0.0.0.0:${PORT}"] diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..28404c6 --- /dev/null +++ b/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 diff --git a/docs/Makefile.inc b/docs/Makefile.inc new file mode 100644 index 0000000..fd39595 --- /dev/null +++ b/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 (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: diff --git a/docs/content/assets/mathjax.js b/docs/content/assets/mathjax.js new file mode 100644 index 0000000..06dbf38 --- /dev/null +++ b/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() +}) diff --git a/docs/content/assets/styles.css b/docs/content/assets/styles.css new file mode 100644 index 0000000..78ee8a7 --- /dev/null +++ b/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; +} diff --git a/docs/content/index.md b/docs/content/index.md new file mode 100644 index 0000000..4a6d9e9 --- /dev/null +++ b/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:")) +} +``` + + +## 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:") + } + } +} +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..61b6ceb --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..1777852 --- /dev/null +++ b/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/ diff --git a/docs/tools/__init__.py b/docs/tools/__init__.py new file mode 100644 index 0000000..09e7437 --- /dev/null +++ b/docs/tools/__init__.py @@ -0,0 +1 @@ +"""Tools""" diff --git a/docs/tools/formatters.py b/docs/tools/formatters.py new file mode 100644 index 0000000..e9de263 --- /dev/null +++ b/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 diff --git a/docs/tools/macro.py b/docs/tools/macro.py new file mode 100644 index 0000000..a59be25 --- /dev/null +++ b/docs/tools/macro.py @@ -0,0 +1,35 @@ +from typing import Optional + +trace_icon = ":fontawesome-solid-route:" +debug_icon = ":fontawesome-solid-bug:" +info_icon = ":fontawesome-solid-circle-info:" +warning_icon = ":fontawesome-solid-triangle-exclamation:" +error_icon = ":fontawesome-solid-circle-exclamation:" +stop_icon = ":fontawesome-solid-circle-xmark:" +true_icon = ":fontawesome-solid-square-check:" +false_icon = ":fontawesome-solid-circle-times:" + +windows_icon = ":fontawesome-brands-windows:" +macos_icon = ":fontawesome-brands-apple:" +linux_icon = ":fontawesome-brands-linux:" + +def define_env(env): + define_macros(env.variables) + +def define_macros(vars): + vars['trace'] = f"{trace_icon}{{.trace}}" + vars['debug'] = f"{debug_icon}{{.debug}}" + vars['info'] = f"{info_icon}{{.info}}" + vars['warning'] = f"{warning_icon}{{.warning}}" + vars['error'] = f"{error_icon}{{.error}}" + vars['stop'] = f"{stop_icon}{{.stop}}" + + # NOTE: `true` and `false` are reserved keywords + vars['yes'] = f"{true_icon}{{.true}}" + vars['no'] = f"{false_icon}{{.false}}" + + vars.os = dict( + windows = f"{windows_icon} Windows", + linux = f"{linux_icon} Linux", + macos = f"{macos_icon} macOS" + ) diff --git a/docs/tools/setup.py b/docs/tools/setup.py new file mode 100644 index 0000000..01e2f1d --- /dev/null +++ b/docs/tools/setup.py @@ -0,0 +1,10 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +"""Setup for the formatters module.""" + +from distutils.core import setup + +setup( + name='formatters', + py_modules=['formatters'], +)