#1506 Repo tooling: Adopt 'docsbuilder' script, update linkchecker command
Merged by james. Opened by ferdnyc.
ferdnyc/packaging-committee makefile-dependencies  into  master

Download 1506.patch

Docsbuilder

Instead of using podman commands directly in the Makefile, add the docsbuilder.sh script from the docs templates repo. Rewrite the Makefile to use docsbuilder commands to perform its functions.

Changes:

  • The preview URL changes from https://localhost:8000 to https://localhost:8080/
  • build is now a synonym for doc
  • serve now runs docsbuilder -p which automatically rebuilds the doc first
  • watch is now available to start a server that automatically rebuilds the preview on file changes
  • linkcheck will automatically start a preview server before running linkchecker (and automatically shut it down after)

Linkchecker

The linkcheck command in the Makefile (which uses the linkchecker script) needed to be updated for both the switch to docsbuilder, and the current version of the tool.

  • The --complete argument is no longer accepted
  • The --ignore rules needed to be expanded for use with docsbuilder's Antora containers.

The Antora server will include a language-switching link and an edit link for each file, both of which aren't valid in the preview and need to be ignored.

The edit link takes the form file:///antora/..., a path that's only valid inside the container.

The language link points from every document https://localhost:8080/guidelines/foo to a language-specific URL like https://localhost:8080/en-US/guidelines/foo

The latter may need to be tweaked if they're dependent on the system locale of the user running linkchecker. Ignoring https://localhost:8080/en-US works for me, but may not be universal.

There are quite a few bad links flagged (14), but for the most part they appear to be genuinely broken links. Except for https://crates.io links for Rust, linkcheck registers all of those as 404s despite the fact they open fine in my browser. They'll probably have to be ignored, I assume it's some sort of robot/scraping protection. (This PR does not include adding that --ignore, though, as I deemed it out of scope.)

rebased onto 9f5fc87ef45921093661452bf42a47fa11993ffa

rebased onto 915b98fdc468cefa80e799b208999f392dbb0c03

Pull-Request has been merged by james

Metadata