Repository navigation
docs: Diátaxis site from Org pages - #17
Merged
Merged
Conversation
The site was the README's text as one Sphinx page, with COMPAT.md and RELEASING.md beside it. It had no tutorial and no task-sized guides, and nothing in the code could be linked by name. The documentation template builds it now. Org pages under docs/orgmode/ are exported to reStructuredText and built by Sphinx with warnings and unresolved names as errors. docs/tools/zig_api.zig writes the API pages from the doc comments of src/main.zig and the files it imports, and zig build docs installs the Zig autodoc site, from a compile of its own so that the binary is not built with -femit-docs. check_site.py checks the internal links and anchors, and that no page names a site; lychee checks the external links. pixi.lock pins the tools, so dependabot no longer watches docs/requirements.txt. The first pages are the tutorial, "Keep a failed build's logs", run with EasyBuild 5.4.2 as the page says; the how-to on calling eb-keep-logs from a build pipeline; the explanation of how failed finds a build's log; and the compatibility table. The contributing page says how to record a change and run the tests, and links RELEASING.md. The docs workflow replaces pages.yml: it builds the site as docbld does, checks the external links, also weekly, and publishes from main.
The API pages and the autodoc show each declaration's doc comment, and its first sentence is the summary in the module's list. 11 of the 19 pub declarations had none, nor had five fields of localtime's Posix and Zone, so their entries were a bare name and a signature. Each now says what it is or does, with the units, limits and errors the code has. The comment at the top of src/localtime.zig said the zone is read the way glibc reads it. In two cases it is not: an empty TZDIR leaves a zone name relative to the working directory, where glibc takes it as unset, and a TZ with a leading ':' that names no file is UTC, where glibc reads the rule string after the ':'. The comment says so now. Only comments change: the release binary is the same file, byte for byte.
COMPAT.md says the Zig build dates runs as date -d does, TZ rules included, and refuses an EB_KEEP_LOGS_NOW that is not an integer. Run side by side with the shell script, it differs in three cases that no row covers: - EB_KEEP_LOGS_NOW set but empty is refused with exit 2; the shell script takes the current time. - With TZDIR set but empty, a zone name in TZ is looked up relative to the working directory, so the zone is UTC; date reads it under /usr/share/zoneinfo. - A TZ with a leading ':' that names no file, such as ':CET-1CEST,M3.5.0,M10.5.0/3', is UTC; date reads the rule after the ':'. A new table lists them as unintended differences, and the two rows that claimed more now say less. The code is unchanged.
The first pages covered one task and one design choice. These are the rest: - how-to guides: rotate a log tree, and mark logs that may carry a licence number; - explanation: how a run's age is reckoned from its name in local time; - reference: the eb-keep-logs command, with its arguments, options, environment, exit statuses, every message it prints and the files it reads and writes, each checked against src/main.zig. The commands on each how-to page were run as the page says, on the run the tutorial made, and their output is pasted from that run. The tutorial, the pipeline how-to and the first explanation link to the new pages, and an italic lead in that explanation no longer holds a literal, which reStructuredText cannot nest.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs for eb-keep-logs, built the same way as zig-common's: Org pages rendered by Sphinx, with the API reference generated from the doc comments.
The site has a tutorial, how-tos for running it in a pipeline, rotating a log tree and marking licensed logs, explanations of how the failed build's log is found and how run ages use local time, and a full command reference that covers every message in
src/main.zig.Every
pubdeclaration now has a doc comment. Only comments change insrc/, and the release binary has the same sha256 at base and tip.COMPAT.mdgains a section on the differences from the shell script that are bugs: an emptyEB_KEEP_LOGS_NOWexits 2, an emptyTZDIRand aTZlike:Namethat names no file both fall back to UTC, and therunAgeDayscomment creditschmodwith moving the mtime.Checks: the strict Sphinx build,
check_site.py, the lychee link check,zig fmt --checkandzig build testall pass.