Jeff King [off-list ref] writes:
As far as CI goes, I am not altogether convinced of the usefulness of
building the documentation. It's very expensive, and the failure mode is
rarely "whoops, running `make doc` failed". It's almost always that the
output looks subtly wrong, but that's very hard to check automatically.
I've seen "make doc" break for me when it works for other people,
and if CI can check the formatting for various combinations of
versions of toolchain components, it would have some value. But
otherwise, I agree that "make doc" in CI would not give us as much
benefit as we spend electricity on it.
If we are to make support for building with AsciiDoctor better, CI
that does "make doc" with both AsciiDoc and AsciiDoctor might be of
help---a "make it buildable with A" patch may accidentally break B
and vice versa.
[1] I think we've also traditionally considered asciidoc to be the
definitive toolchain, and people using asciidoctor are free to
submit patches to make things work correctly in both places. I'm not
opposed to changing that attitude, as it seems like asciidoctor is
faster and more actively maintained these days. But I suspect our
build chain would need some improvements. Last time I tried building
with AsciiDoctor it involved a lot manual tweaking of Makefile
variables. It sounds like Dscho is doing it regularly, though. It
should probably work out of the box (with something like
USE_ASCIIDOCTOR=Yes) if we expect people to actually rely on it.
I do not mind getting convinced to declare that we will swap the
positions of these two documentation toolchains in some future date,
and a good first step for it to happen would be an easier out-of-box
experience.
Thanks.