Add generate-docs command to build task
Some checks failed
Docs / docs (push) Has been cancelled
Docs / deploy (push) Has been cancelled

The Swift Docc has to run in a Linux container to be able to build the
documentation, as it needs access to the inotify.h header files.
This commit is contained in:
T. R. Bernstein
2026-03-12 18:10:31 +01:00
parent 2812ddf210
commit a942b15483
4 changed files with 196 additions and 2 deletions

View File

@@ -4,7 +4,7 @@ The build tool for the Swift Inotify project.
## Overview
`TaskCLI` is a small command-line executable (exposed as `task` in `Package.swift`) that automates project-level workflows. Its primary purpose is running the integration test suite inside a Linux Docker container, so you can validate the inotify-dependent code on the correct platform even when developing on macOS.
`TaskCLI` is a small command-line executable (exposed as `task` in `Package.swift`) that automates project-level workflows. Its primary purpose is running integration tests and generating documentation inside Linux Docker containers, so you can validate inotify-dependent code on the correct platform even when developing on macOS.
### Running the Tests
@@ -19,6 +19,16 @@ This launches a `swift:latest` Docker container with the repository mounted at `
The container is started with `--security-opt systempaths=unconfined` so that the limit tests can write to `/proc/sys/fs/inotify/*`.
### Generating Documentation
```bash
swift run task generate-docs
```
This copies the project to a temporary directory, injects the `swift-docc-plugin` dependency via `swift package add-dependency` (if absent), and runs documentation generation inside a `swift:latest` Docker container. The resulting static sites are written to `./public/inotify/` and `./public/taskcli/`, ready for deployment to GitHub Pages.
The working tree is never modified — all changes happen in the temporary copy, which is cleaned up automatically.
### Verbosity
Pass one or more `-v` flags to increase log output:
@@ -40,7 +50,12 @@ Docker must be installed and running on the host machine. The container uses the
- ``Command``
- ``TestCommand``
- ``GenerateDocsCommand``
### Configuration
- ``GlobalOptions``
### Errors
- ``GenerateDocsError``