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.)
Docsbuilder
Instead of using podman commands directly in the Makefile, add the
docsbuilder.shscript from the docs templates repo. Rewrite the Makefile to use docsbuilder commands to perform its functions.Changes:
https://localhost:8000tohttps://localhost:8080/buildis now a synonym fordocservenow runsdocsbuilder -pwhich automatically rebuilds the doc firstwatchis now available to start a server that automatically rebuilds the preview on file changeslinkcheckwill automatically start a preview server before runninglinkchecker(and automatically shut it down after)Linkchecker
The
linkcheckcommand in the Makefile (which uses thelinkcheckerscript) needed to be updated for both the switch to docsbuilder, and the current version of the tool.--completeargument is no longer accepted--ignorerules 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/footo a language-specific URL likehttps://localhost:8080/en-US/guidelines/fooThe latter may need to be tweaked if they're dependent on the system locale of the user running linkchecker. Ignoring
https://localhost:8080/en-USworks 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.iolinks for Rust,linkcheckregisters 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.)