From: SZEDER Gábor <szeder.dev@gmail.com>
Date: Thu, 28 Aug 2025 18:28:33 GMT
Subject: Re: [PATCH] ci: perform build and smoke tests for Meson docs
Message-ID: <aLCf0UaTxy5Nxpv/@szeder.dev>
In-Reply-To: <20250312-b4-pks-ci-meson-docs-v1-1-5e7cf7ac959a@pks.im>

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@pks.im>
> ---
> 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