On Wed, Mar 12, 2025 at 03:28:54PM +0100, Patrick Steinhardt wrote:
> Our "documentation" CI job performs a couple of tests against our
> documentation. Part of these tests is to check whether documentation
> builds at all and whether it spits out the expected set of files. We
> don't yet have such a test for Meson, which means that we wouldn't
> notice at all if building the documentation were to break. As a result,
> breakages as fixed by 87eccc3a81d (meson: fix building technical and
> howto docs, 2025-03-02) are easy to go unnoticed.
>
> Address this test gap by starting to build both manpages and HTML sites
> as part of the CI job.
>
> Signed-off-by: Patrick Steinhardt <ps@xxxxxx>
> ---
> Hi,
>
> this single patch expands our "documentation" CI job to also start
> building Meson documentation.
>
> Thanks!
>
> Patrick
> ---
> ci/test-documentation.sh | 27 +++++++++++++++++++++------
> 1 file changed, 21 insertions(+), 6 deletions(-)
>
> diff --git a/ci/test-documentation.sh b/ci/test-documentation.sh
> index 6c018b673e0..49f87f50fd7 100755
> --- a/ci/test-documentation.sh
> +++ b/ci/test-documentation.sh
> @@ -15,6 +15,13 @@ filter_log () {
> "$1"
> }
>
> +check_docs () {
> + test -s "$1"/Documentation/git.html &&
> + test -s "$1"/Documentation/git.xml &&
> + test -s "$1"/Documentation/git.1 &&
> + grep "<meta name=\"generator\" content=\"$2 " "$1"/Documentation/git.html
> +}
> +
> make check-builtins
> make check-docs
>
> @@ -23,10 +30,7 @@ make doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)
> cat stderr.raw
> filter_log stderr.raw >stderr.log
> test ! -s stderr.log
> -test -s Documentation/git.html
> -test -s Documentation/git.xml
> -test -s Documentation/git.1
> -grep '<meta name="generator" content="AsciiDoc ' Documentation/git.html
> +check_docs . AsciiDoc
>
> rm -f stdout.log stderr.log stderr.raw
> check_unignored_build_artifacts
> @@ -37,10 +41,21 @@ make USE_ASCIIDOCTOR=1 doc > >(tee stdout.log) 2> >(tee stderr.raw >&2)
> cat stderr.raw
> filter_log stderr.raw >stderr.log
> test ! -s stderr.log
> -test -s Documentation/git.html
> -grep '<meta name="generator" content="Asciidoctor ' Documentation/git.html
> +check_docs . Asciidoctor
>
> rm -f stdout.log stderr.log stderr.raw
> check_unignored_build_artifacts
>
> +# Build docs with Meson and AsciiDoc
> +meson setup build-asciidoc -Ddocs=html,man -Ddocs_backend=asciidoc
> +meson compile -C build-asciidoc
> +check_docs build-asciidoc AsciiDoc
> +rm -rf build-asciidoc
> +
> +# Build docs with Meson and AsciiDoctor
> +meson setup build-asciidoctor -Ddocs=html,man -Ddocs_backend=asciidoctor
> +meson compile -C build-asciidoctor
> +check_docs build-asciidoctor Asciidoctor
> +rm -rf build-asciidoctor
The documentation CI job should only build the documentation, but
these meson commands unnecessarily compile git as well:
https://github.com/git/git/actions/runs/17222438141/job/48860520663#step:4:4679
+ meson compile -C build-asciidoc
ninja: Entering directory `/home/runner/work/git/git/build-asciidoc'
[1/1327] Generating hook-list.h with a custom command
[2/1327] Generating config-list.h with a custom command
[3/1327] Generating GIT-VERSION-FILE with a custom command (wrapped by meson to set env)
[4/1327] Generating command-list.h with a custom command
[5/1327] Generating version-def.h with a custom command (wrapped by meson to set env)
[6/1327] Generating Documentation/asciidoc.conf with a custom command (wrapped by meson to set env)
[7/1327] Generating t/clar-decls.h with a custom command
[8/1327] Generating Documentation/cmds-ancillaryinterrogators.adoc with a custom command
[9/1327] Generating Documentation/mergetools-diff.adoc with a custom command (wrapped by meson to set env)
[10/1327] Compiling C object libcommon-main.a.p/common-main.c.o
[11/1327] Compiling C object libgit.a.p/alias.c.o
[12/1327] Compiling C object libgit.a.p/advice.c.o
[13/1327] Compiling C object libgit.a.p/abspath.c.o
