From 64e8e974bb8bbe1a6eb6167c364bb9058eeed2be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81sbj=C3=B6rn=20Skarph=C3=A9=C3=B0insson?= <42176644+AsiSkarp@users.noreply.github.com> Date: Tue, 15 Oct 2024 21:01:08 +0200 Subject: [PATCH] Initial commit --- .github/workflows/release.yml | 77 ++++++++++++++++++++++++++++++ .github/workflows/tests.yml | 69 +++++++++++++++++++++++++++ .typstignore | 16 +++++++ CHANGELOG.md | 13 +++++ Justfile | 42 +++++++++++++++++ LICENSE | 24 ++++++++++ README.md | 64 +++++++++++++++++++++++++ docs/manual.typ | 0 scripts/package | 86 ++++++++++++++++++++++++++++++++++ scripts/setup | 37 +++++++++++++++ scripts/uninstall | 33 +++++++++++++ src/lib.typ | 0 tests/.gitignore | 2 + tests/.ignore | 3 ++ tests/test1/ref/1.png | Bin 0 -> 3835 bytes tests/test1/test.typ | 1 + typst.toml | 31 ++++++++++++ 17 files changed, 498 insertions(+) create mode 100644 .github/workflows/release.yml create mode 100644 .github/workflows/tests.yml create mode 100644 .typstignore create mode 100644 CHANGELOG.md create mode 100644 Justfile create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/manual.typ create mode 100755 scripts/package create mode 100644 scripts/setup create mode 100755 scripts/uninstall create mode 100644 src/lib.typ create mode 100644 tests/.gitignore create mode 100644 tests/.ignore create mode 100644 tests/test1/ref/1.png create mode 100644 tests/test1/test.typ create mode 100644 typst.toml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..721f477 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,77 @@ +name: Package and push to registry repo +on: + push: + tags: [ v* ] + +env: + # the repository to which to push the release version + # usually a fork of typst/packages (https://github.com/typst/packages/) + # that you have push privileges to + REGISTRY_REPO: author/typst-packages + # the path within that repo where the "/" directory should be put + # for the Typst package registry, keep this as is + PATH_PREFIX: packages/preview + +jobs: + release: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Probe runner package cache + uses: awalsh128/cache-apt-pkgs-action@v1 + with: + packages: cargo + version: 1.0 + + - name: Install just from crates.io + uses: baptiste0928/cargo-install@v3 + with: + crate: just + + - name: Setup typst + uses: typst-community/setup-typst@v3 + with: + typst-version: latest + + - name: Determine and check package metadata + run: | + . scripts/setup + echo "PKG_NAME=${PKG_PREFIX}" >> "${GITHUB_ENV}" + echo "PKG_VERSION=${VERSION}" >> "${GITHUB_ENV}" + + if [[ "${GITHUB_REF_NAME}" != "v${VERSION}" ]]; then + echo "package version ${VERSION} does not match release tag ${GITHUB_REF_NAME}" >&2 + exit 1 + fi + + - name: Build package + run: | + just doc + just package out + + - name: Checkout package registry + uses: actions/checkout@v4 + with: + repository: ${{ env.REGISTRY_REPO }} + token: ${{ secrets.REGISTRY_TOKEN }} + path: typst-packages + + - name: Release package + run: | + mkdir -p "typst-packages/${{ env.PATH_PREFIX }}/$PKG_NAME" + mv "out/${PKG_NAME}/${PKG_VERSION}" "typst-packages/${{ env.PATH_PREFIX }}/${PKG_NAME}" + rmdir "out/${PKG_NAME}" + rmdir out + + GIT_USER_NAME="$(git log -1 --pretty=format:'%an')" + GIT_USER_EMAIL="$(git log -1 --pretty=format:'%ae')" + + cd typst-packages + git config user.name "${GIT_USER_NAME}" + git config user.email "${GIT_USER_EMAIL}" + git checkout -b "${PKG_NAME}-${PKG_VERSION}" + git add . + git commit -m "${PKG_NAME}:${PKG_VERSION}" + git push --set-upstream origin "${PKG_NAME}-${PKG_VERSION}" diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..75d2ec0 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,69 @@ +name: Tests +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + tests: + strategy: + matrix: + # add any other Typst versions that your package should support + typst-version: ["0.11"] + # the docs don't need to build with all versions supported by the package; + # the latest one is enough + include: + - typst-version: "0.11" + doc: 1 + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Probe runner package cache + uses: awalsh128/cache-apt-pkgs-action@v1 + with: + packages: imagemagick cargo + version: 1.0 + + - name: Install oxipng from crates.io + uses: baptiste0928/cargo-install@v3 + with: + crate: oxipng + + - name: Install just from crates.io + uses: baptiste0928/cargo-install@v3 + with: + crate: just + + - name: Install typst-test from github + uses: baptiste0928/cargo-install@v3 + with: + crate: typst-test + git: https://github.com/tingerrr/typst-test.git + tag: ci-semi-stable + + - name: Setup typst + id: setup-typst + uses: typst-community/setup-typst@v3 + with: + typst-version: ${{ matrix.typst-version }} + + - name: Run test suite + run: just test + + - name: Archive diffs + uses: actions/upload-artifact@v4 + if: always() + with: + name: typst-${{ steps.setup-typst.outputs.typst-version }}-diffs + path: | + tests/**/diff/*.png + tests/**/out/*.png + tests/**/ref/*.png + retention-days: 5 + + - name: Build docs + if: ${{ matrix.doc }} + run: just doc diff --git a/.typstignore b/.typstignore new file mode 100644 index 0000000..ba2d170 --- /dev/null +++ b/.typstignore @@ -0,0 +1,16 @@ +# this is not a "standard" ignore file, it's specific to this template's `scripts/package` script +# list any files here that should not be uploaded to Universe when releasing this package + +# if you are used to ignore files, be aware that .typstignore is a bit more limited: +# - only this file is used; .typstignore files in subdirectories are not considered +# - patterns must match file/directory names from the beginning: `x.typ` will not match `src/x.typ` +# - `*` in patterns works, but also matches directory separators: `*.typ` _will_ match `src/x.typ` +# .git and .typstignore are excluded automatically + +.github +scripts +tests +Justfile +# PDF manuals should be included so that they can be linked, but not their sources +docs/* +!docs/*.pdf diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ba20211 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,13 @@ +# [unreleased](https://github.com///releases/tag/) +## Added + +## Removed + +## Changed + +## Migration Guide from v0.1.X + +--- + +# [v0.1.0](https://github.com///releases/tag/v0.1.0) +Initial Release \ No newline at end of file diff --git a/Justfile b/Justfile new file mode 100644 index 0000000..f1a24f7 --- /dev/null +++ b/Justfile @@ -0,0 +1,42 @@ +root := justfile_directory() + +export TYPST_ROOT := root + +[private] +default: + @just --list --unsorted + +# generate manual +doc: + typst compile docs/manual.typ docs/manual.pdf + +# run test suite +test *args: + typst-test run {{ args }} + +# update test cases +update *args: + typst-test update {{ args }} + +# package the library into the specified destination folder +package target: + ./scripts/package "{{target}}" + +# install the library with the "@local" prefix +install: (package "@local") + +# install the library with the "@preview" prefix (for pre-release testing) +install-preview: (package "@preview") + +[private] +remove target: + ./scripts/uninstall "{{target}}" + +# uninstalls the library from the "@local" prefix +uninstall: (remove "@local") + +# uninstalls the library from the "@preview" prefix (for pre-release testing) +uninstall-preview: (remove "@preview") + +# run ci suite +ci: test doc diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..68a49da --- /dev/null +++ b/LICENSE @@ -0,0 +1,24 @@ +This is free and unencumbered software released into the public domain. + +Anyone is free to copy, modify, publish, use, compile, sell, or +distribute this software, either in source code form or as a compiled +binary, for any purpose, commercial or non-commercial, and by any +means. + +In jurisdictions that recognize copyright laws, the author or authors +of this software dedicate any and all copyright interest in the +software to the public domain. We make this dedication for the benefit +of the public at large and to the detriment of our heirs and +successors. We intend this dedication to be an overt act of +relinquishment in perpetuity of all present and future rights to this +software under copyright law. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR +OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +OTHER DEALINGS IN THE SOFTWARE. + +For more information, please refer to diff --git a/README.md b/README.md new file mode 100644 index 0000000..86482a4 --- /dev/null +++ b/README.md @@ -0,0 +1,64 @@ +# The `my-package` Package +
Version 0.1.0
+ +A short description about the project and/or client. + +## Template adaptation checklist + +- [ ] Fill out `README.md` + - Change the `my-package` package name, including code snippets + - Check section contents and/or delete sections that don't apply +- [ ] Check and/or replace `LICENSE` by something that suits your needs +- [ ] Fill out `typst.toml` + - See also the [typst/packages README](https://github.com/typst/packages/?tab=readme-ov-file#package-format) +- [ ] Adapt Repository URLs in `CHANGELOG.md` + - Consider only committing that file with your first release, or removing the "Initial Release" part in the beginning +- [ ] Adapt or deactivate the release workflow in `.github/workflows/release.yml` + - to deactivate it, delete that file or remove/comment out lines 2-4 (`on:` and following) + - to use the workflow + - [ ] check the values under `env:`, particularly `REGISTRY_REPO` + - [ ] if you don't have one, [create a fine-grained personal access token](https://github.com/settings/tokens?type=beta) with [only Contents permission](https://stackoverflow.com/a/75116350/371191) for the `REGISTRY_REPO` + - [ ] on this repo, create a secret `REGISTRY_TOKEN` (at `https://github.com/[user]/[repo]/settings/secrets/actions`) that contains the so created token + + if configured correctly, whenever you create a tag `v...`, your package will be pushed onto a branch on the `REGISTRY_REPO`, from which you can then create a pull request against [typst/packages](https://github.com/typst/packages/) +- [ ] remove/replace the example test case +- [ ] (add your actual code, docs and tests) +- [ ] remove this section from the README + +## Getting Started + +These instructions will get you a copy of the project up and running on the typst web app. Perhaps a short code example on importing the package and a very simple teaser usage. + +```typ +#import "@preview/my-package:0.1.0": * + +#show: my-show-rule.with() +#my-func() +``` + +### Installation + +A step by step guide that will tell you how to get the development environment up and running. This should example how to clone the repo and where to (maybe a link to the typst documentation on it), along with any pre-requisite software and installation steps. + +``` +$ First step +$ Another step +$ Final step +``` + +## Usage + +A more in-depth description of usage. Any template arguments? A complicated example that showcases most if not all of the functions the package provides? This is also an excellent place to signpost the manual. + +```typ +#import "@preview/my-package:0.1.0": * + +#let my-complicated-example = ... +``` + +## Additional Documentation and Acknowledgments + +* Project folder on server: +* Confluence link: +* Asana board: +* etc... diff --git a/docs/manual.typ b/docs/manual.typ new file mode 100644 index 0000000..e69de29 diff --git a/scripts/package b/scripts/package new file mode 100755 index 0000000..57013fb --- /dev/null +++ b/scripts/package @@ -0,0 +1,86 @@ +#!/usr/bin/env bash +set -eu + +# adapted from https://github.com/johannes-wolf/cetz/blob/35c0868378cea5ad323cc0d9c2f76de8ed9ba5bd/scripts/package +# licensed under Apache License 2.0 + +. "$(dirname "${BASH_SOURCE[0]}")/setup" + +if (( $# < 1 )) || [[ "${1:-}" == "help" ]]; then + echo "package TARGET" + echo "" + echo "Packages all relevant files into a directory named '/'" + echo "at TARGET. If TARGET is set to @local or @preview, the local Typst package" + echo "directory will be used so that the package gets installed for local use." + echo "The name and version are read from 'typst.toml' in the project root." + echo "" + echo "Local package prefix: $DATA_DIR/typst/package/local" + echo "Local preview package prefix: $DATA_DIR/typst/package/preview" + exit 1 +fi + +TARGET="$(resolve-target "${1:?Missing target path, @local or @preview}")" +echo "Install dir: $TARGET" + +# ignore rules +readarray -t ignores < <(grep -v '^#' .typstignore | grep '[^[:blank:]]') + +# recursively print all files that are not excluded via .typstignore +function enumerate { + local root="$1" + if [[ -f "$root" ]]; then + echo "$root" + else + local files + readarray -t files < <(find "$root" \ + -mindepth 1 -maxdepth 1 \ + -not -name .git \ + -not -name .typstignore) + # declare -p files >&2 + + local f + for f in "${files[@]}"; do + local include + include=1 + + local ignore + for ignore in "${ignores[@]}"; do + if [[ "$ignore" =~ ^! ]]; then + ignore="${ignore:1}" + if [[ "$f" == ./$ignore ]]; then + # echo "\"$f\" matched \"!$ignore\"" >&2 + include=1 + fi + elif [[ "$f" == ./$ignore ]]; then + # echo "\"$f\" matched \"$ignore\"" >&2 + include=0 + fi + done + if [[ "$include" == 1 ]]; then + enumerate "$f" + fi + done + fi +} + +# List of all files that get packaged +readarray -t files < <(enumerate ".") +# declare -p files >&2 + +TMP="$(mktemp -d)" + +for f in "${files[@]}"; do + mkdir -p "$TMP/$(dirname "$f")" 2>/dev/null + cp -r "$ROOT/$f" "$TMP/$f" +done + +TARGET="${TARGET:?}/${PKG_PREFIX:?}/${VERSION:?}" +echo "Packaged to: $TARGET" +if rm -r "${TARGET:?}" 2>/dev/null; then + echo "Overwriting existing version." +fi +mkdir -p "$TARGET" + +# include hidden files by setting dotglob +shopt -s dotglob +mv "$TMP"/* "$TARGET" diff --git a/scripts/setup b/scripts/setup new file mode 100644 index 0000000..9fe1c85 --- /dev/null +++ b/scripts/setup @@ -0,0 +1,37 @@ +# source this script to prepare some common environment variables + +# adapted from https://github.com/johannes-wolf/cetz/blob/35c0868378cea5ad323cc0d9c2f76de8ed9ba5bd/scripts/package +# licensed under Apache License 2.0 + +# Local package directories per platform +if [[ "$OSTYPE" == "linux"* ]]; then + DATA_DIR="${XDG_DATA_HOME:-$HOME/.local/share}" +elif [[ "$OSTYPE" == "darwin"* ]]; then + DATA_DIR="$HOME/Library/Application Support" +else + DATA_DIR="${APPDATA}" +fi + +function read-toml() { + local file="$1" + local key="$2" + # Read a key value pair in the format: = "" + # stripping surrounding quotes. + perl -lne "print \"\$1\" if /^${key}\\s*=\\s*\"(.*)\"/" < "$file" +} + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")"; pwd -P)/.." # macOS has no realpath +PKG_PREFIX="$(read-toml "$ROOT/typst.toml" "name")" +VERSION="$(read-toml "$ROOT/typst.toml" "version")" + +function resolve-target() { + local target="$1" + + if [[ "$target" == "@local" ]]; then + echo "${DATA_DIR}/typst/packages/local" + elif [[ "$target" == "@preview" ]]; then + echo "${DATA_DIR}/typst/packages/preview" + else + echo "$target" + fi +} diff --git a/scripts/uninstall b/scripts/uninstall new file mode 100755 index 0000000..d57ae16 --- /dev/null +++ b/scripts/uninstall @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +set -eu + +# adapted from https://github.com/johannes-wolf/cetz/blob/35c0868378cea5ad323cc0d9c2f76de8ed9ba5bd/scripts/package +# licensed under Apache License 2.0 + +. "$(dirname "${BASH_SOURCE[0]}")/setup" + +if (( $# < 1 )) || [[ "${1:-}" == "help" ]]; then + echo "uninstall TARGET" + echo "" + echo "Removes the package installed into a directory named '/'" + echo "at TARGET. If TARGET is set to @local or @preview, the local Typst package" + echo "directory will be used so that the package gets installed for local use." + echo "The name and version are read from 'typst.toml' in the project root." + echo "" + echo "Local package prefix: $DATA_DIR/typst/package/local" + echo "Local preview package prefix: $DATA_DIR/typst/package/preview" + exit 1 +fi + +TARGET="$(resolve-target "${1:?Missing target path, @local or @preview}")" +echo "Install dir: $TARGET" + +TARGET="${TARGET:?}/${PKG_PREFIX:?}/${VERSION:?}" +echo "Package to uninstall: $TARGET" +if [[ ! -e "${TARGET:?}" ]]; then + echo "Package was not found." +elif rm -r "${TARGET:?}" 2>/dev/null; then + echo "Successfully removed." +else + echo "Removal failed." +fi diff --git a/src/lib.typ b/src/lib.typ new file mode 100644 index 0000000..e69de29 diff --git a/tests/.gitignore b/tests/.gitignore new file mode 100644 index 0000000..5972bf2 --- /dev/null +++ b/tests/.gitignore @@ -0,0 +1,2 @@ +diff/ +out/ diff --git a/tests/.ignore b/tests/.ignore new file mode 100644 index 0000000..db714de --- /dev/null +++ b/tests/.ignore @@ -0,0 +1,3 @@ +**.png +**.svg +**.pdf diff --git a/tests/test1/ref/1.png b/tests/test1/ref/1.png new file mode 100644 index 0000000000000000000000000000000000000000..e726341630977abfd37e94771ee645ced9a94f11 GIT binary patch literal 3835 zcmeH|_fr$t7RLjjm`D?dbVli&1rY-#fD%dqgp!~Vss<2Q2nwMiLgK&b*oT!{f~T;mkeXduPt)e&^gI2eg$SSQ-of z00fcN2qyr5hXw%fWt;#W?uhE9`2YaiAr7`!3l4|FX0yM4|Ni{>b1p8fgoK3N-d-ms zr=p^w{r&yduV3@>@@{W$!{P9;u`w|*F;P)bK0dz1#YGVjkryvs7#kbs<>ftm_>iBU zAB93~Y-}toEfo|Lz+f;ch#xVSh20|QxE+1=gUva&KWGqb6wDNj$&vuDrR z+S>N@^{uU~(P*^H%uF;IJv=;IQBg5IJ{}nvIX^$|>gp;fDf#i^$DyI2?(Xiuz`&-a zriO+FU0q!!lX>dYDI$@G$KxFw9Msj-V`F3O?Cff4YQSKyqobpOf(}Y&X?b~he}8`~D=R9MYHx3EVPSFg>eWx5KI!P_XlrW+1qD5L@SwQ3*vrccfk2Q* zr10?Y+1Xhe8ykIneRFg3?Ck8EoSfCw)#&Kxn3$OL_4Tc-t-``W2m~@RGIIL#X(J;e zBodjMn>#o-7#|-W6&0nZsQBp7BMl7=VPWCU&Q3u=K~+`N)YMcdDJcShU}$J4EiJvW zvQl4Pucf7xl$2CmUG3xJ6A}_4Cnwj~*a(F}84QMri3tve!(cF>p`mm-y{f9Jwzk&K z&kqCwefaRf*VlJ+baY~3;^fJbrlzJTDJcR10&Z?@3kwT8JUo{!T~bj|dHM3?z`(%U zw{P9u-GzjNc6N5e#l=fYOTT^l*3;AT>eVY{Wn~}`I5#&J92_hmAu%&E^X1Ez&CSh- zh=}Iq=JN7#Zf@?hw6y&E{Pgtn{{H^Gy}dVY-W(hpRFd4P0004VB;pb_Vtl3N-k~J{ zqyjcwg3f)E{tv^KM(_yuWfq#+RkbhUn@d0U>R&K7twi+%y~t6?B4j`YGU=K|t(Q&h z4J6*@83Kes#LpFKRW58S-dfA|zC&o5fXh%`EU-(bsyZiz|D%m0EB(W@WqLk}%Q9Lm zC_U@9VjT^73Tjg`r-jKh9_+Zg5r5zEKzcR&eWI{1IWpKrVlTXm(-)}dH6A;1;(iS4MZ~S1M?*XEq@+6t`5_WzyTWyJ<2EG%)1i zM^8oUY)6T_RaM5VSld0r)TC~I*TL6gP;^+PEGXjOiTG_zmbgZVIt@dpmB04bLO;f| zOuk#@rfuu>mX`@OC9&%bIi_Yr7Q!z8P=zV9zvbn~IXoScnIRF~Y73tHDX{a$D`_ys z5*B9&7*U6#`gK9QUly3Rfs+LOym+n~DgXqP5N_&hY68Ui(=wbAp6n;iEpRZ94vK{l z#Xl2CG8t3Cn@iW^CQoJ$Y@vZkK>#S|%#HksRqU$Vr((?#@F?BL#pi3s*C&HO;sCx@ zdhLqm&*rF3Ar3DZr3#R9;!9VrrR;h6AGO6Dwp=Rf9YphBh;&CASzf8*Dc1WH$%01n zL9ySZNV3Zz}@^DaA7Wp0t|F?|wA zmTwmhP8nbEdknE2?=!=(_CBKM?bjLuYw*3)dmwtX*No!skjA>(@~H1mu^u6*Kq#pz zKgMquuME3r?HW>z!(`!PwHRtbLT+wzanoy;-7;*An2=i-|9PqLJh=DMzHE5sa6UDw zPj;0R#RgRo^UH&jth!)>LiqVWa;~-&S*asPY-o#TrCv6)UWtOMAvXYwu zfNejRI6CW^D7m;sT&;+U%U>G^-rc6Wdbo1ep`zV{c;Lo_=1o#4urPM-%u}jN0*XVo-&sXKeyxfO9BaSsK}ph@GUNo=P#AV#X|y+?P;?=alPg= zoWdR>`8xum4}e@pyv}e&EFJz%d|W>sUjN7gC2*+Hk-J2;I1LvBj