Horton

Re: meson documentation build open issues

Peter Eisentraut <peter@eisentraut.org>

View thread View on postgr.es
From: Peter Eisentraut <peter@eisentraut.org>
To: Andres Freund <andres@anarazel.de>
Cc: Christoph Berg <myon@debian.org>, Alvaro Herrera <alvherre@alvh.no-ip.org>, pgsql-hackers@lists.postgresql.org, Andrew Dunstan <andrew@dunslane.net>, Tom Lane <tgl@sss.pgh.pa.us>
Date: 2023-11-09T14:32:39Z
Lists: pgsql-hackers 
On 09.11.23 01:59, Andres Freund wrote:
>> I think we could build doc/src/sgml/postgres-full.xml by default.  That
>> takes less than 0.5 seconds here and it's an intermediate target for html
>> and man.
> That does require the docbook dtd to be installed, afaict. I think we would
> need a configure test for that to be present if we want to build it by
> default, otherwise we'll cause errors on plenty systems that don't get them
> today.  The docbook dts aren't a huge dependency, but still. Some OSs might
> not have a particularly install source for them, e.g. windows.

I was thinking we would do it only if the required tools are found. 
Basically like

  postgres_full_xml = custom_target('postgres-full.xml',
    input: 'postgres.sgml',
    output: 'postgres-full.xml',
    depfile: 'postgres-full.xml.d',
    command: [xmllint, '--nonet', '--noent', '--valid',
              '--path', '@OUTDIR@', '-o', '@OUTPUT@', '@INPUT@'],
    depends: doc_generated,
-  build_by_default: false,
+  build_by_default: xmllint_bin.found(),
  )

Besides giving you a quick validity check of the XML, this also builds 
the doc_generated, which draw from non-doc source files, so this would 
also serve to check that those are sound and didn't mess up the docs.

> I don't think that'd detect the missing ids?

Right, it wouldn't do that.

Commits

  1. docs: meson: Change what 'docs' target builds

  2. meson: Add 'world' target

  3. meson: Document build targets, add 'help' target

  4. meson: docs: Add {html,man} targets, rename install-doc-*

  5. docs: Document --with-selinux/-Dselinux options centrally

  6. meson: Change default of 'selinux' feature option to auto

  7. meson: Fix doc installation path computation

  8. meson: Install missing example files

  9. meson: docs: Install all manpages, not just ones in man1

  10. meson: docs: Allow configuring simple/website style

  11. docs: html: load stylesheet via custom.css.source

  12. docs: html: copy images to output as part of xslt build

  13. meson: docs: Preparatory cleanups

  14. docs: Remove support for 'htmlhelp' format

  15. meson: add install-{docs,doc-html,doc-man} targets

  16. meson: add install-{quiet, world} targets

  17. meson: make install_test_files more generic, rename to install_files

  18. meson: rename html_help target to htmlhelp