Horton

Re: meson documentation build open issues

Andres Freund <andres@anarazel.de>

View thread View on postgr.es
From: Andres Freund <andres@anarazel.de>
To: Christoph Berg <myon@debian.org>, Peter Eisentraut <peter.eisentraut@enterprisedb.com>, Andrew Dunstan <andrew@dunslane.net>, Tom Lane <tgl@sss.pgh.pa.us>, pgsql-hackers <pgsql-hackers@postgresql.org>
Date: 2023-11-08T23:21:21Z
Lists: pgsql-hackers

Attachments

Hi,

I really like the idea of an 'help' target that prints the targets. It seemed
annoying to document such targets in both the sgml docs and the input for a
the help target. Particularly due to the redundancies between id attributes,
the target name etc.

First I generated the list of targets from within meson.build, only to later
realize that that would not work when building the docs via make. So I instead
added doc/src/sgml/meson-targets.txt which is lightly postprocessed for the
'help' target, and slightly more processed when building the docs.

That does have some downsides, e.g. it'd be more complicated to only print
targets if a relevant option is enabled. But I think it's acceptable that way.


Example output:

$ ninja help
[0/1 1   0%] Running external command help (wrapped by meson to set env)
Code Targets:
  all                          Build everything other than documentation
  backend                      Build backend and related modules
  bin                          Build frontend binaries
  contrib                      Build contrib modules
  pl                           Build procedual languages

Documentation Targets:
  docs                         Build documentation in multi-page HTML format
  doc-html                     Build documentation in multi-page HTML format
  doc-man                      Build documentation in man page format
  doc/src/sgml/postgres-A4.pdf Build documentation in PDF format, with A4 pages
  doc/src/sgml/postgres-US.pdf Build documentation in PDF format, with US letter pages
  doc/src/sgml/postgres.html   Build documentation in single-page HTML format
  alldocs                      Build documentation in all supported formats

Installation Targets:
  install                      Install postgres, excluding documentation
  install-doc-html             Install documentation in multi-page HTML format
  install-doc-man              Install documentation in man page format
  install-docs                 Install documentation in multi-page HTML and man page formats
  install-quiet                Like "install", but installed files are not displayed
  install-world                Install postgres, including multi-page HTML and man page documentation
  uninstall                    Remove installed files

Other Targets:
  clean                        Remove all build products
  test                         Run all enabled tests (including contrib)
  world                        Build everything, including documentation
  help                         List important targets


Because of the common source, some of the descriptions in the state of this
patch are a bit shorter than in the preceding commit. But I don't think that
hurts much.

Greetings,

Andres Freund

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