docs: migrate from mdbook to hugo (#764)

.github/workflows/ci.yml

@@ -326,23 +326,19 @@ jobs:
     needs: test
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
+          fetch-depth: 0
       - uses: abbbi/github-actions-tune@v1
-      - uses: actions/cache@v4
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
         with:
-          key: ${{ env.CACHE_KEY }}-${{ hashFiles('**/Cargo.toml') }}
-          path: |
-            ~/.cargo/bin/
-            ~/.cargo/git/db/
-            ~/.cargo/registry/cache/
-            ~/.cargo/registry/index/
-            target/
-      - uses: dtolnay/rust-toolchain@nightly
-      - name: "Install `mdbook`"
+          hugo-version: 'latest'
+          extended: true
+      - name: Build
         run: |
-          cargo install -f mdbook
-      - run: |
-          mdbook build docs/book
-          mdbook test docs/book
+          cd docs
+          hugo --minify
 
   gh-pages:
     if: ${{ github.ref == 'refs/heads/main' }}
@@ -374,15 +370,13 @@ jobs:
             ~/.cargo/registry/index/
             target/
       - uses: dtolnay/rust-toolchain@nightly
-      - name: "Install `mdbook`"
-        run: |
-          cargo install -f mdbook
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: 'latest'
+          extended: true
       - run: |
-          mkdir -p target/docs
-          cargo doc --all --no-deps --workspace --target-dir target/docs/api
-          mdbook build docs/book --dest-dir ../../target/docs/book
-          echo '<meta http-equiv="refresh" content="0; url=doc/pica/index.html"><a href=doc/pica/index.html">Redirect</a>' >> target/docs/api/index.html
-          echo '<meta http-equiv="refresh" content="0; url=book/index.html"><a href=book/index.html">Redirect</a>' >> target/docs/index.html
+          make docs
       - uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}

Makefile

@@ -5,6 +5,7 @@ MAKEFLAGS += -rR
 
 DESTDIR=
 CARGO ?= cargo
+HUGO ?= hugo
 PREFIX=/usr/local
 BINDIR=$(PREFIX)/bin
 
@@ -29,6 +30,15 @@ fmt:
 doc:
 	$(CARGO) doc --no-deps
 
+docs:
+	mkdir -p target/docs
+	$(CARGO) doc --all --no-deps --workspace --target-dir target/docs/api
+	$(HUGO) --minify --gc --source docs --destination ../target/docs/book
+	echo '<meta http-equiv="refresh" content="0; url=doc/pica/index.html"><a href=doc/pica/index.html">Redirect</a>' \
+		> target/docs/api/index.html
+	echo '<meta http-equiv="refresh" content="0; url=book/index.html"><a href=book/index.html">Redirect</a>' \
+		> target/docs/index.html
+
 release:
 	$(CARGO) build --workspace --all-features --release
 	$(CARGO) test --workspace --all-features --release
@@ -39,4 +49,4 @@ install: release
 clean:
 	$(CARGO) clean
 
-.PHONY: build clean check clippy test fmt doc release install
+.PHONY: build clean check clippy test fmt doc docs release install

ci/prepare-tests.sh

@@ -3,7 +3,7 @@
 set -euo pipefail
 # set -x
 
-DIRS=$(find docs/book/src/referenz/kommandos -type f -iname "*.md" -print)
+DIRS=$(find docs/content/docs/kommandos -type f -iname "*.md" -print)
 DUMP="tests/data/DUMP.dat.gz"
 
 for i in $DIRS; do

crates/pica-toolkit/tests/snapshot.rs

@@ -34,14 +34,14 @@ fn cli_tests() {
 #[test]
 fn doc_tests() {
     trycmd::TestCases::new()
-        .case("../../docs/book/src/referenz/kommandos/count.md")
-        .case("../../docs/book/src/referenz/kommandos/filter.md")
-        .case("../../docs/book/src/referenz/kommandos/frequency.md")
-        .case("../../docs/book/src/referenz/kommandos/explode.md")
-        .case("../../docs/book/src/referenz/kommandos/hash.md")
-        .case("../../docs/book/src/referenz/kommandos/invalid.md")
-        .case("../../docs/book/src/referenz/kommandos/partition.md")
-        .case("../../docs/book/src/referenz/kommandos/print.md")
-        .case("../../docs/book/src/referenz/kommandos/slice.md")
-        .case("../../docs/book/src/referenz/kommandos/split.md");
+        .case("../../docs/content/docs/kommandos/count.md")
+        .case("../../docs/content/docs/kommandos/filter.md")
+        .case("../../docs/content/docs/kommandos/frequency.md")
+        .case("../../docs/content/docs/kommandos/explode.md")
+        .case("../../docs/content/docs/kommandos/hash.md")
+        .case("../../docs/content/docs/kommandos/invalid.md")
+        .case("../../docs/content/docs/kommandos/partition.md")
+        .case("../../docs/content/docs/kommandos/print.md")
+        .case("../../docs/content/docs/kommandos/slice.md")
+        .case("../../docs/content/docs/kommandos/split.md");
 }

docs/.gitignore

@@ -0,0 +1,4 @@
+content/docs/kommandos/*.in/
+/public
+/resources/_gen/
+/.hugo_build.lock

docs/config.toml

@@ -0,0 +1,17 @@
+baseURL = "https://deutsche-nationalbibliothek.github.io/pica-rs/book/"
+languageCode = "de-DE"
+title = "pica-rs"
+
+enableGitInfo = true
+
+[markup.goldmark.renderer]
+unsafe = true
+
+[module]
+[[module.imports]]
+path = "github.com/alex-shpak/hugo-book"
+
+[params]
+BookComments = false
+BookSearch = false
+BookToc = false

docs/book/src/README.md → docs/content/_index.md

@@ -1,11 +1,12 @@
-<p align="center"><img  height="250" width="250" src="images/pica-rs_logo.png"></p>
+---
+title: Einführung
+type: docs
+---
 
 <center>
-
-[![CI](https://github.com/deutsche-nationalbibliothek/pica-rs/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/deutsche-nationalbibliothek/pica-rs/actions/workflows/ci.yml)
-[![Documentation](https://img.shields.io/badge/Documentation-main-orange.svg)](https://deutsche-nationalbibliothek.github.io/pica-rs/)
-[![dependency status](https://deps.rs/repo/github/deutsche-nationalbibliothek/pica-rs/status.svg)](https://deps.rs/repo/github/deutsche-nationalbibliothek/pica-rs)
-
+    <a href="/">
+        <img  height="250" width="250" src="/pica-rs/book/images/logo.png" />
+    </a>
 </center>
 
 Das Toolkit _pica-rs_ ermöglicht eine effiziente Verarbeitung von
@@ -31,19 +32,14 @@ mögliche Fehler, Fragen und neue Ideen als [GitHub-Issues][Issues]
 anzulegen. Diese werden wir dann intern beraten und möglichst zeitnah
 ein Feedback geben.
 
-## Verwandte Projekte
-
-- [Catmandu::Pica](https://metacpan.org/pod/Catmandu::PICA) — Catmandu modules for working with PICA+ data
-- [Metafacture](https://github.com/metafacture) — Tool suite for metadata processing
-
+[Kommandos]: {{< relref "docs/kommandos/" >}}
 
 [AE]: https://blog.dnb.de/erschliessungsmaschine-gestartet/
 [DNB]: https://www.dnb.de/
 [Dokumentation]: https://deutsche-nationalbibliothek.github.io/pica-rs/book/
 [Installation]: https://deutsche-nationalbibliothek.github.io/pica-rs/book/anleitungen/installation.html
 [Issues]: https://github.com/deutsche-nationalbibliothek/pica-rs/issues
 [KI]: https://www.dnb.de/DE/Professionell/ProjekteKooperationen/Projekte/KI/ki_node.html
-[Kommandos]: referenz/kommandos/index.md
 [OCLC]: https://www.oclc.org/
 [Pandas]: https://pandas.pydata.org/
 [Polars]: https://www.pola.rs/

docs/content/docs/anleitungen/_index.md

@@ -0,0 +1,35 @@
+---
+bookFlatSection: true
+---
+
+# Kommandos
+
+## Übersicht
+
+* **[cat]** --- Zusammenfügen (Konkatenieren) von Datensätzen
+* **[convert]** --- Konvertierung zwischen verschiedenen PICA-Formaten
+* **[completions]** --- Erzeugung von Shell-Skripten zur Autovervollständigung
+* **[count]** --- Zählen von Datensätzen, Feldern und Unterfeldern
+* **[explode]** --- Teilt Datensätze in Lokal- oder Exemplardatensätze auf
+* **[filter]** --- Filtert Datensätze anhand eines Kriteriums
+* **[frequency]** --- Ermitteln einer Häufigkeitsverteilung über ein oder mehrere Unterfelder
+* **[hash]** --- Erzeugt SHA-256-Hashwerte von Datensätzen
+* **[invalid]** --- Findet ungültige Zeilen in der Eingabe
+* **[partition]** --- Partitioniert Datensätze anhand eines Unterfelds
+* **[print]** --- Gibt Datensätze in einer menschenlesbaren Form aus
+* **[slice]** --- Ausschneiden eines zusammenhängenden Teilbereichs aus der Eingabe
+* **[split]** --- Teilt eine Menge an Datensätzen in Dateien fester Größe
+
+[cat]: {{< relref "cat.md" >}}
+[completions]: {{< relref "completions.md" >}}
+[convert]: {{< relref "convert.md" >}}
+[count]: {{< relref "count.md" >}}
+[explode]: {{< relref "explode.md" >}}
+[filter]: {{< relref "filter.md" >}}
+[frequency]: {{< relref "frequency.md" >}}
+[hash]: {{< relref "hash.md" >}}
+[invalid]: {{< relref "invalid.md" >}}
+[partition]: {{< relref "partition.md" >}}
+[print]: {{< relref "print.md" >}}
+[slice]: {{< relref "slice.md" >}}
+[split]: {{< relref "split.md" >}}

docs/book/src/anleitungen/installation.md → docs/content/docs/installation.md

@@ -1,4 +1,5 @@
 # Installation
+
 Das Toolkit _pica-rs_ kann unter Linux, macOS und Windows verwendet
 werden. Für diese Betriebssysteme stehen unterschiedliche Pakete zum
 [Download auf GitHub](https://github.com/deutsche-nationalbibliothek/pica-rs/releases)

docs/content/docs/kommandos/_index.md

@@ -0,0 +1,35 @@
+---
+bookFlatSection: true
+---
+
+# Kommandos
+
+## Übersicht
+
+* **[cat]** --- Zusammenfügen (Konkatenieren) von Datensätzen
+* **[convert]** --- Konvertierung zwischen verschiedenen PICA-Formaten
+* **[completions]** --- Erzeugung von Shell-Skripten zur Autovervollständigung
+* **[count]** --- Zählen von Datensätzen, Feldern und Unterfeldern
+* **[explode]** --- Teilt Datensätze in Lokal- oder Exemplardatensätze auf
+* **[filter]** --- Filtert Datensätze anhand eines Kriteriums
+* **[frequency]** --- Ermitteln einer Häufigkeitsverteilung über ein oder mehrere Unterfelder
+* **[hash]** --- Erzeugt SHA-256-Hashwerte von Datensätzen
+* **[invalid]** --- Findet ungültige Zeilen in der Eingabe
+* **[partition]** --- Partitioniert Datensätze anhand eines Unterfelds
+* **[print]** --- Gibt Datensätze in einer menschenlesbaren Form aus
+* **[slice]** --- Ausschneiden eines zusammenhängenden Teilbereichs aus der Eingabe
+* **[split]** --- Teilt eine Menge an Datensätzen in Dateien fester Größe
+
+[cat]: {{< relref "cat.md" >}}
+[completions]: {{< relref "completions.md" >}}
+[convert]: {{< relref "convert.md" >}}
+[count]: {{< relref "count.md" >}}
+[explode]: {{< relref "explode.md" >}}
+[filter]: {{< relref "filter.md" >}}
+[frequency]: {{< relref "frequency.md" >}}
+[hash]: {{< relref "hash.md" >}}
+[invalid]: {{< relref "invalid.md" >}}
+[partition]: {{< relref "partition.md" >}}
+[print]: {{< relref "print.md" >}}
+[slice]: {{< relref "slice.md" >}}
+[split]: {{< relref "split.md" >}}