threads / patch / 63101

patchci: perform build and smoke tests for Meson docs

Subject: [PATCH] ci: perform build and smoke tests for Meson docs

## tl;dr

3 messages between Mar 12, 2025 and Sep 11, 2025. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Patrick Steinhardt· Mar 12, 2025, 14:28 UTC · lore

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(-)
Show changes to ci/test-documentation.sh +21 −6
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
+
 save_good_tree

---
base-commit: 87a0bdbf0f72b7561f3cd50636eee33dcb7dbcc3
change-id: 20250312-b4-pks-ci-meson-docs-1fb10b67ebef
SZEDER Gábor· Aug 28, 2025, 18:28 UTC · re: Patrick Steinhardt · lore

Re: [PATCH] ci: perform build and smoke tests for Meson docs

On Wed, Mar 12, 2025 at 03:28:54PM +0100, Patrick Steinhardt wrote:
Show 77 quoted lines
> 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
Patrick Steinhardt· Sep 11, 2025, 07:48 UTC · re: SZEDER Gábor · lore

Re: [PATCH] ci: perform build and smoke tests for Meson docs

On Thu, Aug 28, 2025 at 08:28:33PM +0200, SZEDER Gábor wrote:
Show 20 quoted lines
> 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
Indeed. I'll send a patch for this in a bit. Thanks!
Patrick

← back to recent threads