Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 0 additions & 8 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,3 @@ updates:
dependencies:
patterns:
- "*"
- package-ecosystem: pip
directory: /docs
schedule:
interval: monthly
groups:
docs:
patterns:
- "*"
64 changes: 64 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# Build the documentation the way `pixi run -e docs docbld` does: Org export,
# API pages from the code, Sphinx with warnings and unresolved references as
# errors, the Zig autodoc site, and the internal link check. External links
# are checked in their own step. On main the site is published to
# https://stackhands.github.io/eb-keep-logs/.
name: docs

on:
push:
branches: [main]
pull_request:
workflow_dispatch:
schedule:
# Weekly, so a link that went dead elsewhere is noticed.
- cron: "17 5 * * 1"

permissions:
contents: read

concurrency:
group: docs-${{ github.ref }}
cancel-in-progress: true

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- uses: prefix-dev/setup-pixi@9936258fee697aff89b3fed6ca1f80a382ef694e # v0.11.3
with:
environments: docs
cache: true
locked: true

- name: Build
run: pixi run -e docs docbld
env:
DOCS_SOURCE_REF: ${{ github.sha }}

- name: External links
run: pixi run -e docs linkcheck
env:
GITHUB_TOKEN: ${{ github.token }}

- uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: docs/build/html

deploy:
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
needs: build
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
39 changes: 0 additions & 39 deletions .github/workflows/pages.yml

This file was deleted.

14 changes: 14 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,16 @@
.zig-cache/
zig-out/
zig-pkg/

# Documentation build (docs-plan template): generated, never committed.
/docs/build/
/docs/source/**/*.rst
/docs/source/reference/api/
/docs/source/**/*.png
/docs/source/**/*.svg
/docs/source/**/*.jpg
/docs/source/**/*.webp
!/docs/source/_static/**
/docs/**/__pycache__/
/.pixi/
/.lycheecache
14 changes: 12 additions & 2 deletions COMPAT.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ on the same invocations.
| `eb` | `eb --last-log [--tmp-logdir=TMP_LOGDIR] --output-style=basic`, and the same without `--output-style` when that fails or prints nothing; the last line printed is the log |
| stdout | `Failed build log: LOGDIR/NAME.failed.ebout.log`, `Failed command output: LOGDIR/NAME.failed.command-{out,err}.txt`, `Failed meson test log: LOGDIR/NAME.failed.meson-testlog.txt`, `Failed command output not kept: EASYBUILD_TMPDIR is not set.`, `Failed command output not kept: PATH is not under EASYBUILD_TMPDIR.`, `Failed command output not kept: PATH belongs to another user.`, `No EasyBuild log to keep for NAME.`, `No EasyBuild log to keep for NAME: eb is not on PATH.`, `No EasyBuild log to keep for NAME: eb --last-log exited N.`, `No EasyBuild log to keep for NAME: PATH is another build's log.`, `eb-keep-logs rotate: N files compressed, M runs deleted under ROOT`, with `1 file` and `1 run` for a count of one; LOGDIR in these lines without its trailing slashes |
| files | kept files closed to others (command streams mode 0600), their resolved paths appended to `LOGDIR/.licensed-logs` unless already listed; on a failure, `NAME.stdout.log`, a TMP_LOGDIR below LOGDIR and the regular files directly in it closed to others, a symbolic link left as it is; `rotate` writes `FILE.gz` with the file's mode and updates `.licensed-logs` to the `.gz` path |
| run ages | days from the local midnight of the date in the run's name, as `date -d YYYYMMDD` computes it, including TZ rules; a run whose local midnight does not exist is skipped |
| run ages | days from the local midnight of the date in the run's name, as `date -d YYYYMMDD` computes it, including TZ rules, except in the two cases of `TZ` and `TZDIR` under unintended differences; a run whose local midnight does not exist is skipped |
| the run in progress | `rotate` neither compresses nor deletes the run that holds its stdout or stderr, when either is a regular file, or `EB_PIPELINE_LOG_DIR` |

## Deliberate differences
Expand All @@ -25,7 +25,7 @@ on the same invocations.
| no arguments, `--help` | prints a trailing half sentence from the script's header | stops after the `--version` line |
| `--version` | `eb-keep-logs 0.1.0` | `eb-keep-logs 0.2.1 (TARGET, MODE, zig VERSION, COMMIT)`; the first two words are unchanged |
| `--compress-after` or `--delete-after` with no value after it | never returns | refused, exit 2 |
| `EB_KEEP_LOGS_NOW` not an integer | evaluated as shell arithmetic | refused, exit 2 |
| `EB_KEEP_LOGS_NOW` not empty and not an integer | evaluated as shell arithmetic | refused, exit 2 |
| a copy into LOGDIR fails | error from cp, then the file is still listed and reported | error on stderr; the file is neither listed nor reported |
| a copy into an existing LOGDIR file fails part way (a full disk) | cp truncates the file first, so the previous bytes are gone | the previous file is left unchanged; nothing is listed or reported |
| a symbolic link or non-regular file at a destination name in LOGDIR | cp writes through it | refused, reported on stderr |
Expand All @@ -38,3 +38,13 @@ on the same invocations.
| a log larger than 1 GiB | scanned | copied, not checked for another build and not scanned for the command output or meson paths, with a message on stderr |
| a meson testlog larger than 1 GiB | kept unless its summary shows every test passing | kept without reading the summary, with a message on stderr |
| a log with NUL bytes | `grep` reports a binary match and the scan finds nothing | scanned as text |

## Unintended differences

The Zig build differs here without meaning to; each is a bug in the Zig build.

| case | shell script | Zig build |
|---|---|---|
| `EB_KEEP_LOGS_NOW` set but empty | the current time | refused, exit 2: `eb-keep-logs: EB_KEEP_LOGS_NOW must be seconds since the epoch, not ''` |
| `TZDIR` set but empty, `TZ` naming a zone file | the file under `/usr/share/zoneinfo`, as `date` reads it | the name is looked up relative to the working directory, so the zone is UTC unless a file of that name is there |
| `TZ` with a leading `:` that names no file, such as `:CET-1CEST,M3.5.0,M10.5.0/3` | the rule string after the `:`, as `date` reads it | UTC |
11 changes: 11 additions & 0 deletions build.zig
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,17 @@ pub fn build(b: *std.Build) void {
const exe = b.addExecutable(.{ .name = "eb-keep-logs", .root_module = mod, .linkage = .static });
b.installArtifact(exe);

// The Zig autodoc site, into <prefix>/docs (pixi task autodoc). A compile
// of its own: asking the installed one for docs would add -femit-docs to
// every build of the binary.
const doc_exe = b.addExecutable(.{ .name = "eb-keep-logs", .root_module = mod });
const docs = b.addInstallDirectory(.{
.source_dir = doc_exe.getEmittedDocs(),
.install_dir = .prefix,
.install_subdir = "docs",
});
b.step("docs", "Generate the API reference").dependOn(&docs.step);

const unit = b.addTest(.{ .root_module = mod });
b.step("unit", "Run the unit tests").dependOn(&b.addRunArtifact(unit).step);

Expand Down
1 change: 1 addition & 0 deletions changelog.d/+compat-unintended.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
COMPAT.md lists three differences between the Zig build and the shell script that are bugs, not choices: an empty `EB_KEEP_LOGS_NOW` is refused instead of meaning the current time, an empty `TZDIR` leaves a zone name relative to the working directory, and a `TZ` with a leading `:` that names no file is UTC. Its rows on `EB_KEEP_LOGS_NOW` and on run ages no longer claim more than the Zig build does.
1 change: 1 addition & 0 deletions changelog.d/+doc-comments.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Every `pub` declaration has a doc comment, whose first sentence is the summary the API pages list, and the comment at the top of `src/localtime.zig` names the two cases in which the zone is read differently from glibc: an empty `TZDIR`, and a `TZ` with a leading `:` that names no file.
1 change: 1 addition & 0 deletions changelog.d/+docs-pages.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The site has how-to guides for rotating a log tree and marking logs that may carry a licence number; an explanation of how a run's age is reckoned from its name in local time; and a reference of the `eb-keep-logs` command: its arguments, options, environment variables, exit statuses, every message it prints and the files it reads and writes.
1 change: 1 addition & 0 deletions changelog.d/+docs-site.doc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The documentation site is built from Org pages in `docs/orgmode/` with Sphinx, in four parts: the tutorial "Keep a failed build's logs", how-to guides, explanation and reference. The API pages are generated from the doc comments of `src/main.zig` and the files it imports, and `zig build docs` installs the Zig autodoc site. `pixi run -e docs docbld` builds it as CI does and fails on a warning, an unresolved name or a dead internal link; `pixi run -e docs linkcheck` checks the external links. The `docs` workflow publishes the site to GitHub Pages; `docs/requirements.txt` and `pages.yml` are gone.
2 changes: 0 additions & 2 deletions docs/compat.md

This file was deleted.

69 changes: 0 additions & 69 deletions docs/conf.py

This file was deleted.

Loading
Loading