RE: Improve docs syntax checking and enable it in the meson build - Mailing list pgsql-hackers

Dear Nazir,

> > 01.
> > I found that postgres core was built when I ran `meson test --suite doc`
> > command, but ideally it's not needed. Per my experiment, we must clarify
> > dependencies for the test, something like below.
> >
> > ```
> > --- a/doc/src/sgml/meson.build
> > +++ b/doc/src/sgml/meson.build
> > @@ -337,7 +337,8 @@ test(
> >    'doc' / 'sgml_syntax_check',
> >    meson_bin,
> >    args: ['compile', postgres_full_xml_target],
> > -  suite: 'doc'
> > +  suite: 'doc',
> > +  depends: doc_generated,
> >  )
> > ```
> 
> Sorry, I didn't understand what you meant, could you please elaborate?

Sure. Let's consider the below scenario, that I wanted to just verify the syntax
of documentations. For the autoconf/make build system, below commands can avoid
building C sources and generate needed .sgml files.

```
$ ./configure
...
$ cd doc/src/sgml/
$ make check 
{ \
  echo "<!ENTITY version \"19devel\">"; \
  echo "<!ENTITY majorversion \"19\">"; \
} > version.sgml
'/usr/bin/perl' ./mk_feature_tables.pl YES ../../../src/backend/catalog/sql_feature_packages.txt
../../../src/backend/catalog/sql_features.txt> features-supported.sgml
 
'/usr/bin/perl' ./mk_feature_tables.pl NO ../../../src/backend/catalog/sql_feature_packages.txt
../../../src/backend/catalog/sql_features.txt> features-unsupported.sgml
 
'/usr/bin/perl' ./generate-errcodes-table.pl ../../../src/backend/utils/errcodes.txt > errcodes-table.sgml
'/usr/bin/perl' ./generate-keywords-table.pl . > keywords-table.sgml
'/usr/bin/perl' ./generate-targets-meson.pl targets-meson.txt generate-targets-meson.pl > targets-meson.sgml
'/usr/bin/perl' ../../../src/backend/utils/activity/generate-wait_event_types.pl --docs
../../../src/backend/utils/activity/wait_event_names.txt
'/usr/bin/perl' ./sgml_syntax_check.pl --srcdir .
/usr/bin/xmllint --nonet --path . --path . --output postgres-full.xml --noent --valid postgres.sgml
```

In case of meson build system, however, added test was run after all C files
were built. Ideally it is not needed.

```
$ meson setup ../postgres/
...
$ meson test --suite doc
ninja: Entering directory `/home/hayato/builddir'
[884/2468] Compiling C object ...                    // C sources were built here
...
```

Also, I have been working on a project which translates the documentation [1],
and the syntax check is used for the github CI. I'm very sad if building
everything is needed to just check the doc.

> 'postgres_full_xml_target' target already depends on 'doc_generated'
> and 'sgml_check_stamp' targets.

I'm not faimilar with Meson, but my theory is that Meson cannot understand that
the test only depends on postgres_full_xml. That's why all sources are built.

Based on the discussion, the fix should be like;

```
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -337,7 +337,8 @@ test(
   'doc' / 'sgml_syntax_check',
   meson_bin,
   args: ['compile', postgres_full_xml_target],
-  suite: 'doc'
+  suite: 'doc',
+  depends: postgres_full_xml
 )
```

[1]: https://github.com/pgsql-jp/jpug-doc

Best regards,
Hayato Kuroda
FUJITSU LIMITED