blob: 0a5ea18c363c306aabdae9ff194354a5d6af0e12 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
|
# ziglang-docs-epub
Turns the [Zig language reference](https://ziglang.org/documentation/) into an
**EPUB**, one per Zig version. CI runs it on a schedule and commits the resulting
`.epub` files back into [`epubs/`](epubs/).
## Why
The reference ships as a single self-contained HTML page. This tool repackages it
as a standards-compliant EPUB3 so you can read it offline in any e-reader.
## How it works
Four decoupled concerns, each a small module that does one thing:
| Module | Responsibility |
| ------------- | --------------------------------------------------------- |
| `index.zig` | discover versions + docs URLs from `download/index.json` |
| `fetch.zig` | HTTP GET via `std.http.Client` |
| `html.zig` | transform the page HTML5 → well-formed XHTML5 |
| `epub.zig` | assemble the EPUB3 container |
| `zip.zig` | minimal, reproducible ZIP writer (stored entries) |
No external runtime dependencies — Zig's standard library provides HTTP and
CRC32. EPUB entries are stored uncompressed (Zig 0.15.2's std deflate
*compressor* is unfinished), which keeps the writer trivial and fully
spec-compliant at the cost of larger files. Output is **byte-for-byte
reproducible** (fixed ZIP timestamps), so CI only commits when the upstream docs
actually change.
## Usage
Requires **Zig 0.15.2**.
```sh
zig build run # build every version that has docs
zig build run -- 0.15.2 # build only specific version(s)
zig build test # run unit tests
```
EPUBs land in `epubs/zig-<version>.epub`.
## Continuous integration
`.forgejo/workflows/build-epubs.yml` runs on [Codeberg](https://codeberg.org)
(Forgejo Actions): daily, on push to `main`, and on manual dispatch. It installs
Zig, runs the tool, and commits any changed EPUBs with `[skip ci]`.
## License
Licensed under the [Apache License 2.0](LICENSE).
|
