Add SwiftPackageIndex configuration file

Add GitHub workflow file to generate docs
Update README section about docs generation
2026-03-15 20:06:26 +01:00 · 2026-03-15 20:06:26 +01:00 · 2026-03-15 20:06:26 +01:00 · 2026-03-15 20:06:21 +01:00
10 changed files with 379 additions and 8 deletions
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,61 @@
 name: Docs
 on:
  push:
    branches:
    - main
  workflow_dispatch:
 permissions:
  contents: read
  pages: write
  id-token: write
 concurrency:
  group: "pages"
  cancel-in-progress: true
 jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - name: Set up Pages
      uses: actions/configure-pages@v5
    - name: Set up Swift
      uses: swift-actions/setup-swift@v3
      with:
        skip-verify-signature: true
    - name: Generate Docs
      run: |
        swift package add-dependency --from 1.4.0 "https://github.com/apple/swift-docc-plugin.git"
        for target in Inotify TaskCLI; do
          lower="${target,,}"
          mkdir -p "./public/$lower"
          swift package --allow-writing-to-directory "./public/$lower" \
            generate-documentation --disable-indexing --transform-for-static-hosting \
            --target "$target" \
            --hosting-base-path "swift-inotify/$lower" \
            --output-path "./public/$lower"
        done
    - name: Copy Index Page
      run: |
        cp ./.github/workflows/index.tpl.html public/index.html
        sed -i -e 's/{{project.name}}/Swift Inotify/g' public/index.html
        sed -i -e 's/{{project.tagline}}/🗂️ Monitor filesystem events on Linux using modern Swift concurrency/g' public/index.html
        sed -i -e 's|{{project.links}}|<li><a href="inotify/documentation/inotify/">Inotify</a>: The actual library.</li><li><a href="taskcli/documentation/taskcli/">TaskCLI</a>: The project build command.</li>|g' public/index.html
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v4
      with:
        path: ./public
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: docs
    steps:
    - name: Deploy Docs
      uses: actions/deploy-pages@v4
--- a/.github/workflows/index.tpl.html
+++ b/.github/workflows/index.tpl.html
@@ -0,0 +1,72 @@
 <!doctype html>
 <html>
 	<head>
 		<title>Astzweig | Swift Inotify</title>
 		<meta name="description" content="Monitor filesystem events on Linux using modern Swift concurrency.">
 		<meta name="viewport" content="width=device-width, initial-scale=1.0">
 		<meta charset="utf-8">
 		<style>
 			:root {
 			  color-scheme: light dark;
 			}
 			html, body {
 				font-family: system-ui, sans-serif;
 				background-color: ligh-dark(#ffffff, #000000);
 				color: ligh-dark(#000000, #ffffff);
 			}
 			main {
 				max-width: min(40em, 100vw);
 				min-height: 80vh;
 				margin: 1rem auto;
 				display: flex;
 				flex-direction: column;
 				align-items: center;
 			}
 			svg {
 				max-width: 12em;
 				margin: 1rem;
 			}
 			footer {
 				max-width: min(60em, 100vw);
 				margin: 1rem auto;
 				font-size: .7rem;
 				font-family: ui-monospace, monospace;
 				h1 {
 					font-size: 1rem;
 				}
 			}
 		</style>
 	</head>
 	<body>
 		<main>
 			<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 531 118"><g fill-rule="evenodd"><style>g { fill: #000; } @media (prefers-color-scheme: dark) { g { fill: #fff; } }</style><g fill-rule="nonzero"><path d="M147.81 96.877q-6.907 0-13.474-1.579t-10.55-4.009l5.703-12.975q3.777 2.3 8.88 3.662t10.034 1.362q4.752 0 6.621-1.01t1.87-2.77q0-1.541-1.732-2.308t-4.578-1.176a920 920 0 0 0-6.258-.874q-3.411-.465-6.859-1.35t-6.293-2.623-4.577-4.71-1.731-7.64q0-5.14 3.057-9.184t8.95-6.424 14.379-2.38q5.783 0 11.612 1.147 5.83 1.147 9.881 3.416l-5.703 12.976q-4.046-2.3-8.033-3.15-3.99-.85-7.58-.85-4.799 0-6.782 1.11-1.984 1.11-1.984 2.7 0 1.602 1.73 2.42 1.732.819 4.578 1.258 2.846.438 6.259.904 3.413.465 6.824 1.385 3.411.918 6.258 2.641t4.578 4.68 1.73 7.594q0 4.932-3.037 8.98t-9.012 6.413-14.76 2.364m59.104 0q-10.4 0-16.173-5.125-5.772-5.124-5.772-15.555V29.652h19v46.314q0 2.966 1.567 4.614t4.126 1.648q3.334 0 5.752-1.748l4.748 13.28q-2.476 1.591-5.97 2.354-3.495.763-7.278.763m-29.88-38.87V43.835h39.252v14.174zM224.539 96V84.831l30.465-35.037 3.203 6.144h-32.931V41.766h48.283v11.168l-30.466 35.038-3.265-6.144h34.739V96zM294.751 96l-19.217-54.234h17.988l15.268 45.362h-8.625l15.969-45.362h16.128l15.363 45.362h-8.417l15.768-45.362h16.697L352.425 96h-18.432l-12.957-37.528h5.543L313.184 96zM404.332 96.877q-9.597 0-16.768-3.639-7.17-3.638-11.115-9.995t-3.946-14.395q0-8.175 3.88-14.498t10.65-9.891q6.77-3.57 15.261-3.57 8.007 0 14.593 3.278t10.504 9.547q3.917 6.27 3.917 15.258 0 1.046-.084 2.34a87 87 0 0 1-.185 2.37H388.1v-9.968h32.863l-7.228 2.806q.031-3.697-1.414-6.397t-3.957-4.213-5.932-1.513-5.983 1.513-3.957 4.23-1.395 6.474v2.903q0 3.966 1.68 6.885t4.776 4.448 7.355 1.53q4.049 0 6.902-1.156t5.584-3.496l10 10.41q-3.876 4.268-9.587 6.503-5.71 2.236-13.475 2.236M439.997 96V41.8h19V96zm9.5-60.2q-5.199 0-8.4-2.9-3.2-2.9-3.2-7.2t3.2-7.2q3.201-2.9 8.4-2.9 5.2 0 8.4 2.75t3.2 7.05q0 4.5-3.15 7.45t-8.45 2.95m48.242 80.477q-7.852 0-14.92-1.779-7.07-1.778-11.985-5.301l6.888-13.26q3.324 2.655 8.413 4.215t9.893 1.559q7.651 0 11.04-3.338t3.388-9.77v-6.369l1-15.23-.087-15.263v-9.975h18.087v44.328q0 15.403-8.304 22.793t-23.413 7.39m-3.376-23.06q-7.18 0-13.226-3.25t-9.7-9.119-3.654-13.845q0-7.975 3.654-13.844 3.654-5.87 9.7-9.07t13.226-3.2q6.976 0 11.836 2.77t7.433 8.572 2.573 14.772q0 8.97-2.573 14.773-2.573 5.804-7.433 8.622-4.86 2.82-11.836 2.82m4.51-15.117q3.444 0 6.103-1.395t4.17-3.907q1.51-2.512 1.51-5.795 0-3.351-1.51-5.829-1.512-2.477-4.17-3.822-2.66-1.344-6.102-1.344-3.346 0-6.054 1.344-2.71 1.345-4.253 3.822-1.545 2.478-1.545 5.83 0 3.282 1.545 5.794 1.544 2.513 4.253 3.907 2.707 1.395 6.054 1.395"/></g><path d="M102.666 13.772h-.014v20.424q2.888.297 5.777.823l.886.167a3.66 3.66 0 0 1 2.96 3.592v53.253a3.66 3.66 0 0 1-2.96 3.595A74 74 0 0 1 95.137 97a75 75 0 0 1-14.267-1.38 3.66 3.66 0 0 1-2.963-3.59V73.025L48.733 58.685l-16.18 12.641a3.66 3.66 0 0 1-4.743-.198 89 89 0 0 1-6.423-6.61V76.41a.84.84 0 0 1-.839.84H9.625v-6.275h5.462V62.61H6.684v5.437H.383V57.175c0-.463.375-.839.838-.839h13.816a90 90 0 0 1-4.592-7.441 3.66 3.66 0 0 1 .95-4.653L55.14 10.064a3.66 3.66 0 0 1 4.743.206 92 92 0 0 1 4.114 4.076L80.529 2.338l-.011-.015c7.448-5.467 22.318-.83 22.148 11.45m-20.448 8.263-7.713 5.812a90 90 0 0 1 2.747 4.647 3.66 3.66 0 0 1-.951 4.654L63.132 47.436l14.773 7.362V38.785a3.66 3.66 0 0 1 2.969-3.596 78 78 0 0 1 4.593-.744v-9.294h-.008v-.387c-.012-1.379-.215-4.408-3.085-2.818zm.946-9.41-12.606 9.497a88 88 0 0 1 2.437 3.42l7.589-5.718-.005-.008.067-.065c1.184-1.096 7.144-4.065 7.558 4.454l.013.324q.01.303.01.622h-.01v8.984q2.065-.194 4.124-.273V19.77h-.036c-.113-7.551-3.735-10.214-8.96-7.25zm-1.004-8.07-16.292 11.83a88 88 0 0 1 3.007 3.563l12.505-9.423-.022-.028q.314-.25.662-.48l.248-.16c4.557-2.813 12.944-2.85 12.838 9.914h-.016l.001 14.038h.045q2.384 0 4.767.155V13.772h-.013c.142-7.384-9.941-14.798-17.73-9.216"/></g></svg>
 			<hgroup>
 				<h1>{{project.name}}</h1>
 				<p>{{project.tagline}}</p>
 			</hgroup>
 			<h2>Documentations</h2>
 			<ul>
 				{{project.links}}
 			</ul>
 		</main>
 		<footer vocab="https://schema.org/" typeof="Organization">
 			© <span property="legalName">Astzweig GmbH &amp; Co. KG</span>,
 			based in
 			<span property="location">Freiburg i. Br.</span>,
 			entered in the commercial register of the Freiburg Local Court under number HRA 703853 and VAT ID number:
 			<span property="vatID">DE297037836</span>.
 			The general partner is
 			<span property="parentOrganization" typeof="Organization">
 				<span property="legalName">Astzweig Verwaltungsgesellschaft mbH</span>
 				based in <span property="location">Freiburg i.Br.</span>,
 				entered in the commercial register of the same court under number HRB 718037 and with a capital of €25,000.00, represented by the managing director
 				<span property="employee" type="Person"><span property="givenName">Thomas R.</span> <span property="familyName">Bernstein</span>.</span>
 			</span>
 		</footer>
 	</body>
 </html>
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 .build
 public
--- a/.spi.yml
+++ b/.spi.yml
@@ -0,0 +1,5 @@
 version: 1
 builder:
  configs:
    - documentation_targets: [Inotify, TaskCLI]
      platform: Linux
--- a/Package.swift
+++ b/Package.swift
@@ -47,6 +47,7 @@ let package = Package(
 				.product(name: "ArgumentParser", package: "swift-argument-parser"),
 				.product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
 				.product(name: "Logging", package: "swift-log"),
 				.product(name: "_NIOFileSystem", package: "swift-nio"),
 				.product(name: "Subprocess", package: "swift-subprocess"),
 				.product(name: "Noora", package: "Noora")
 			]
--- a/README.md
+++ b/README.md
@@ -123,18 +123,15 @@ Use `-v`, `-vv`, or `-vvv` to increase log verbosity. The command runs two passe
 Docker must be installed and running on your machine.
-## Documentation
+### Documentation
 Full API documentation is available as DocC catalogs bundled with the package. Generate them locally with:
 ```bash
-# Inotify library
+swift run task generate-docs
 swift package generate-documentation --target Inotify
 # Task build tool
 swift package generate-documentation --target TaskCLI
 ```
 Then open the files in the newly created `public` folder.
 Or preview in Xcode by selecting **Product > Build Documentation**.
 ## Requirements
--- a/Sources/TaskCLI/Command.swift
+++ b/Sources/TaskCLI/Command.swift
@@ -4,6 +4,6 @@ import ArgumentParser
 struct Command: AsyncParsableCommand {
 	static let configuration = CommandConfiguration(
 		abstract: "Project tasks of Astzweig's Swift Inotify project.",
-		subcommands: [TestCommand.self]
+		subcommands: [TestCommand.self, GenerateDocumentationCommand.self]
 	)
 }
--- a/Sources/TaskCLI/DoccFinder.swift
+++ b/Sources/TaskCLI/DoccFinder.swift
@@ -0,0 +1,37 @@
 import _NIOFileSystem
 public struct DoccFinder {
 	static let fileManager = FileSystem.shared
 	public static func getTargetsWithDocumentation(at paths: String...) async throws -> [String] {
 		try await Self.getTargetsWithDocumentation(at: paths)
 	}
 	static func getTargetsWithDocumentation(at paths: [String]) async throws -> [String] {
 		var resolved: [String] = []
 		for path in paths {
 			let itemPath = FilePath(path)
 			try await withSubdirectories(at: itemPath) { targetPath in
 				print("Target path is", targetPath.description)
 				try await withSubdirectories(at: targetPath) { subdirectory in
 					guard subdirectory.description.hasSuffix(".docc") else { return }
 					guard let target = targetPath.lastComponent?.description else { return }
 					resolved.append(target)
 				}
 			}
 		}
 		return resolved
 	}
 	private static func withSubdirectories(at path: FilePath, body: (FilePath) async throws -> Void) async throws {
 		let directoryHandle = try await fileManager.openDirectory(atPath: path)
 		for try await childContent in directoryHandle.listContents() {
 			guard childContent.type == .directory else { continue }
 			try await body(childContent.path)
 		}
 		try await directoryHandle.close()
 	}
 }
--- a/Sources/TaskCLI/GenerateDocumentation
+++ b/Sources/TaskCLI/GenerateDocumentation
@@ -0,0 +1,182 @@
 import ArgumentParser
 import AsyncAlgorithms
 import Foundation
 import Logging
 import Noora
 import Subprocess
 struct GenerateDocumentationCommand: AsyncParsableCommand {
 	static let configuration = CommandConfiguration(
 		commandName: "generate-documentation",
 		abstract: "Generate DocC documentation of all targets inside a Linux container.",
 		aliases: ["gd"],
 	)
 	@OptionGroup var global: GlobalOptions
 	private static let doccPluginURL = "https://github.com/apple/swift-docc-plugin.git"
 	private static let doccPluginMinVersion = "1.4.0"
 	private static let skipItems: Set<String> = [".git", ".build", ".swiftpm", "public"]
 	// MARK: - Run
 	func run() async throws {
 		let noora = Noora()
 		let logger = global.makeLogger(labeled: "swift-inotify.cli.task.generate-documentation")
 		let fileManager = FileManager.default
 		let projectDirectory = URL(fileURLWithPath: fileManager.currentDirectoryPath)
 		let targets = try await Self.targets(for: projectDirectory)
 		noora.info("Generating DocC documentation on Linux.")
 		logger.debug("Current directory", metadata: ["current-directory": "\(projectDirectory.path(percentEncoded: false))", "targets": "\(targets.joined(separator: ", "))"])
 		let tempDirectory = try copyProject(from: projectDirectory)
 		logger.info("Copied project to temporary directory.", metadata: ["path": "\(tempDirectory.path(percentEncoded: false))"])
 		defer {
 			try? fileManager.removeItem(at: tempDirectory)
 			logger.info("Cleaned up temporary directory.")
 		}
 		try await injectDoccPluginDependency(in: tempDirectory, logger: logger)
 		let script = Self.makeRunScript(for: targets)
 		logger.debug("Container script", metadata: ["script": "\(script)"])
 		let dockerResult = try await Subprocess.run(
 			.name("docker"),
 			arguments: [
 				"run", "--rm",
 				"-v", "\(tempDirectory.path(percentEncoded: false)):/code",
 				"--platform", "linux/arm64",
 				"-w", "/code",
 				"swift:latest",
 				"/bin/bash", "-c", script,
 			],
 			preferredBufferSize: 10,
 		) { execution, standardInput, standardOutput, standardError in
 			print("")
 			let stdout = standardOutput.lines()
 			let stderr = standardError.lines()
 			for try await line in merge(stdout, stderr) {
 				noora.passthrough("\(line)")
 			}
 			print("")
 		}
 		guard dockerResult.terminationStatus.isSuccess else {
 			noora.error("Documentation generation failed.")
 			return
 		}
 		try copyResults(from: tempDirectory, to: projectDirectory)
 		try Self.generateIndexHTML(
 			templateURL: projectDirectory.appending(path: ".github/workflows/index.tpl.html"),
 			outputURL: projectDirectory.appending(path: "public/index.html")
 		)
 		noora.success(
 			.alert("Documentation generated successfully.",
 				takeaways: targets.map {
 					"./public/\($0.lowercased())/"
 				}
 			)
 		)
 	}
 	private static func generateIndexHTML(templateURL: URL, outputURL: URL) throws {
 		var content = try String(contentsOf: templateURL, encoding: .utf8)
 		let replacements: [(String, String)] = [
 			("{{project.name}}", "Swift Inotify"),
 			("{{project.tagline}}", "🗂️ Monitor filesystem events on Linux using modern Swift concurrency"),
 			("{{project.links}}", """
 				<li><a href="inotify/documentation/inotify/">Inotify</a>: The actual library.</li>\
 				<li><a href="taskcli/documentation/taskcli/">TaskCLI</a>: The project build command.</li>
 				"""),
 		]
 		for (placeholder, value) in replacements {
 			content = content.replacingOccurrences(of: placeholder, with: value)
 		}
 		try FileManager.default.createDirectory(
 			at: outputURL.deletingLastPathComponent(),
 			withIntermediateDirectories: true
 		)
 		try content.write(to: outputURL, atomically: true, encoding: .utf8)
 	}
 	private static func targets(for projectDirectory: URL) async throws -> [String] {
 		let sourcesDirectory = projectDirectory.appending(path: "Sources").path
 		let testsDirectory = projectDirectory.appending(path: "Tests").path
 		return try await DoccFinder.getTargetsWithDocumentation(at: sourcesDirectory, testsDirectory)
 	}
 	private static func makeRunScript(for targets: [String]) -> String {
 		targets.map {
 			"mkdir -p \"./public/\($0.localizedLowercase)\" && " +
 			"swift package --allow-writing-to-directory \"\($0.localizedLowercase)\" " +
 			"generate-documentation --disable-indexing --transform-for-static-hosting " +
 			"--target \"\($0)\" " +
 			"--hosting-base-path \"\($0.localizedLowercase)\" " +
 			"--output-path \"./public/\($0.localizedLowercase)\""
 		}.joined(separator: " && ")
 	}
 	// MARK: - Project Copy
 	private func copyProject(from source: URL) throws -> URL {
 		let fileManager = FileManager.default
 		let tempDirectory = fileManager.temporaryDirectory.appending(path: "swift-inotify-docs-\(UUID().uuidString)")
 		try fileManager.createDirectory(at: tempDirectory, withIntermediateDirectories: true)
 		let contents = try fileManager.contentsOfDirectory(at: source, includingPropertiesForKeys: nil)
 		for item in contents {
 			guard !Self.skipItems.contains(item.lastPathComponent) else { continue }
 			try fileManager.copyItem(at: item, to: tempDirectory.appending(path: item.lastPathComponent))
 		}
 		return tempDirectory
 	}
 	private func copyResults(from tempDirectory: URL, to projectDirectory: URL) throws {
 		let fileManager = FileManager.default
 		let source = tempDirectory.appending(path: "public")
 		let destination = projectDirectory.appending(path: "public")
 		if fileManager.fileExists(atPath: destination.path(percentEncoded: false)) {
 			try fileManager.removeItem(at: destination)
 		}
 		try fileManager.copyItem(at: source, to: destination)
 	}
 	// MARK: - Dependency Injection
 	private func injectDoccPluginDependency(in directory: URL, logger: Logger) async throws {
 		let result = try await Subprocess.run(
 			.name("swift"),
 			arguments: [
 				"package", "--package-path", directory.path(percentEncoded: false),
 				"add-dependency", "--from", Self.doccPluginMinVersion, Self.doccPluginURL
 			],
 		) { _ in }
 		guard result.terminationStatus.isSuccess else {
 			throw GenerateDocumentationError.dependencyInjectionFailed
 		}
 		logger.info("Injected swift-docc-plugin dependency.")
 	}
 }
 enum GenerateDocumentationError: Error, CustomStringConvertible {
 	case dependencyInjectionFailed
 	var description: String {
 		switch self {
 		case .dependencyInjectionFailed:
 			"Failed to add swift-docc-plugin dependency to Package.swift."
 		}
 	}
 }
--- a/Sources/TaskCLI/TaskCLI.docc/TaskCLI.md
+++ b/Sources/TaskCLI/TaskCLI.docc/TaskCLI.md
@@ -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-documentation
 ```
 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``
 - ``GenerateDocumentationCommand``
 ### Configuration
 - ``GlobalOptions``
 ### Errors
 - ``GenerateDocsError``
Author	SHA1	Message	Date
T. R. Bernstein	e153f15d43	Add SwiftPackageIndex configuration file Some checks failed Docs / docs (push) Has been cancelled Details Docs / deploy (push) Has been cancelled Details	2026-03-15 20:06:26 +01:00
T. R. Bernstein	430713c741	Add GitHub workflow file to generate docs	2026-03-15 20:06:26 +01:00
T. R. Bernstein	4efc27dd3a	Update README section about docs generation Show how to generate the Docc docs using task CLI instead of faning out to swift package docc plugin.	2026-03-15 20:06:26 +01:00
T. R. Bernstein	239374704a	Add generate-docs command to build task 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.	2026-03-15 20:06:21 +01:00