docs: Overhaul manual and asset workflow

- Completely overhauls the manual to use `mantys:1.0.0`.
- Updates the just file for simpler example generation
- Removes examples from repo
- Updates github workflow

.github/workflows/tests.yml

@@ -12,35 +12,28 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
-      - name: Probe runner package cache
-        uses: awalsh128/cache-apt-pkgs-action@latest
-        with:
-          packages: imagemagick cargo
-          version: 1.0
-
-      - name: Install nu from crates.io
+      - name: Install oxipng from crates.io
         uses: baptiste0928/[email protected]
         with:
-          crate: nu
+          crate: oxipng
 
       - name: Install just from crates.io
         uses: baptiste0928/[email protected]
         with:
           crate: just
 
-      - name: Install typst-test from github
+      - name: Install tytanic from crates.io
         uses: baptiste0928/[email protected]
         with:
-          crate: typst-test
-          git: https://github.com/tingerrr/typst-test.git
-          tag: ci-semi-stable
+          crate: tytanic
+          version: 0.1.0
 
       - name: Setup typst
         uses: yusancky/setup-typst@v2
         with:
           version: 'v0.12.0'
 
-      - name: Run test suite
+      - name: Run test suite and check assets
         run: just ci
 
       - name: Archive artifacts

.gitignore

@@ -0,0 +1,5 @@
+# fonts are currently temporary
+/assets/fonts/**
+
+# all out diretories are temporary
+/**/out/**

CHANGELOG.md

@@ -4,6 +4,10 @@
 ## Removed
 
 ## Changed
+The following internal types have been renamed, because the types are only named in the documentation and did not change signature their renames are semver compatible.
+- `context` -> `hydra-context`
+- `hydra-selector` -> `full-selector`
+- `sanitized-selector` -> `hydra-selector`
 
 ## Fixed
 

Justfile

@@ -1,57 +1,83 @@
-set shell := ['nu', '-c']
+_doc := 'doc'
+_assets := 'assets'
+_examples := _assets / 'examples'
+_showcase := _assets / 'showcase'
 
 export TYPST_ROOT := justfile_directory()
+export TYPST_FONT_PATHS := justfile_directory() / 'assets' / 'fonts'
 
 # list recipes
 [private]
 default:
-	just --list
-
-# generate example images
-gen-examples:
-	rm --recursive --force pages examples/pages
-	mkdir examples/pages
-	typst compile --ppi 300 examples/pages.typ examples/pages/{n}.png
-	typst compile examples/main.typ examples/example.png
-	rm --recursive --force pages examples/pages
-	oxipng --opt max examples/example.png
-
-# generate doc examples
-gen-doc-examples:
-	#! /usr/bin/env nu
-	ls doc/examples
-		| where type == dir
-		| get name
-		| each {|it|
-			cd $it
-			rm --recursive --force out
-			mkdir out
-			[a b] | each {|it|
-				(typst compile
-					$"($it).typ"
-					$"out/($it){n}.png")
-			};
-			let pages = (ls out | length) / 2 | into int;
-			{ pages: $pages } | to toml | save -f out.toml
-		}
-		| ignore
-
-	oxipng --recursive --opt max doc
-
-# generate the manual
-doc: gen-doc-examples
-	typst compile doc/manual.typ doc/manual.pdf
+	@just --list --unsorted
 
 # run the test suite
+[positional-arguments]
 test *args:
-	typst-test run {{ args }}
+	tt run "$@"
 
 # update the test suite
+[positional-arguments]
 update *args:
-	typst-test update {{ args }}
+	tt update "$@"
+
+# clean all output directories
+clean:
+	rm --recursive --force {{ _doc / 'out' }}
+	rm --recursive --force {{ _examples / 'book' / 'out' }}
+	rm --recursive --force {{ _examples / 'skip' / 'out' }}
+	rm --recursive --force {{ _showcase / 'out' }}
+	tt util clean
+
+# run the ci checks locally
+ci: generate-doc generate-showcase (test '--no-fail-fast')
+
+# update the showcase image
+update-showcase: generate-showcase
+	oxipng --opt max {{ _showcase / 'out' / 'showcase.png' }}
+	cp {{ _showcase / 'out' / 'showcase.png' }} {{ _assets / 'showcase.png' }}
+
+# generate the showcase image
+generate-showcase: (clear-directory (_showcase / 'out'))
+	typst compile \
+		--ppi 300 \
+		{{ _showcase / 'pages.typ' }} \
+		{{ _showcase / 'out' / '{n}.png' }}
+	typst compile \
+		{{ _showcase / 'showcase.typ' }} \
+		{{ _showcase / 'out' / 'showcase.png' }}
+
+# generate all doc examples
+generate-examples: (generate-example 'book') (generate-example 'skip')
 
-# run the ci test suite
-ci:
-	# run one single test first to avoid a race condition on package downloads
-	typst-test run regressions/scoped-search
-	typst-test run
+# generate a single doc example
+generate-example example: (clear-directory (_examples / example / 'out'))
+	typst compile \
+		--ppi 300 \
+		{{ _examples / example / 'a.typ' }} \
+		{{ _examples / example / 'out' / 'a{n}.png' }}
+	typst compile \
+		--ppi 300 \
+		{{ _examples / example / 'b.typ' }} \
+		{{ _examples / example / 'out' / 'b{n}.png' }}
+
+# generate a new manual and update it
+update-doc: generate-doc
+	cp {{ _doc / 'out' / 'manual.pdf' }} {{ _assets / 'manual.pdf' }}
+
+# generate the manual
+generate-doc: (clear-directory (_doc / 'out')) generate-examples
+	typst compile \
+		{{ _doc / 'manual.typ' }} \
+		{{ _doc / 'out' / 'manual.pdf' }}
+
+# watch the manual
+watch-doc: (clear-directory (_doc / 'out')) generate-examples
+	typst watch \
+		{{ _doc / 'manual.typ' }} \
+		{{ _doc / 'out' / 'manual.pdf' }}
+
+[private]
+clear-directory dir:
+	rm --recursive --force {{ dir }}
+	mkdir {{ dir }}

README.md

@@ -27,7 +27,7 @@ your document only when it is needed.
 == Second Section
 #lorem(100)
 ```
-![ex]
+![showcase]
 
 ## Documentation
 For a more in-depth description of hydra's functionality and the reference read its [manual].
@@ -39,6 +39,6 @@ For contributing, please take a look [CONTRIBUTING][contrib].
 The package name hydra /ˈhaɪdrə/ is a word play headings and headers, inspired by the monster in
 greek and roman mythology resembling a serpent with many heads.
 
-[ex]: examples/example.png
-[manual]: doc/manual.pdf
+[showcase]: assets/showcase.png
+[manual]: assets/manual.pdf
 [contrib]: CONTRIBUTING.md

assets/.gitignore

@@ -0,0 +1 @@
+fonts/**

doc/examples/book/a.typ → assets/examples/book/a.typ

@@ -1,3 +1,3 @@
-#import "/doc/examples/template.typ": example
+#import "../template.typ": example
 #show: example.with(book: false)
 #include "content.typ"

doc/examples/book/b.typ → assets/examples/book/b.typ

@@ -1,3 +1,3 @@
-#import "/doc/examples/template.typ": example
+#import "../template.typ": example
 #show: example.with(book: true)
 #include "content.typ"

doc/examples/skip/a.typ → assets/examples/skip/a.typ

@@ -1,3 +1,3 @@
-#import "/doc/examples/template.typ": example
+#import "../template.typ": example
 #show: example.with(skip-starting: true)
 #include "content.typ"

doc/examples/skip/b.typ → assets/examples/skip/b.typ

@@ -1,3 +1,3 @@
-#import "/doc/examples/template.typ": example
+#import "../template.typ": example
 #show: example.with(skip-starting: false)
 #include "content.typ"

examples/main.typ → assets/showcase/showcase.typ

@@ -9,7 +9,7 @@
     grid(
       columns: 4,
       gutter: 1em,
-      ..range(1, 5).map(i => image("pages/" + str(i) + ".png"))
+      ..range(1, 5).map(i => image("out/" + str(i) + ".png"))
     ),
   ),
 )