From 619fb4f7b2289bbf2bda9156d866b89451cac70e Mon Sep 17 00:00:00 2001 From: Andres Freund Date: Wed, 8 Nov 2023 15:03:00 -0800 Subject: [PATCH v2 6/7] meson: Add 'help' target, build docs from a common source file Author: Reviewed-by: Discussion: https://postgr.es/m/ Backpatch: --- meson.build | 7 + doc/src/sgml/Makefile | 3 + doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/generate-meson-targets.pl | 63 +++++++ doc/src/sgml/installation.sgml | 231 +------------------------ doc/src/sgml/meson-targets.txt | 38 ++++ doc/src/sgml/meson.build | 9 + 7 files changed, 122 insertions(+), 230 deletions(-) create mode 100644 doc/src/sgml/generate-meson-targets.pl create mode 100644 doc/src/sgml/meson-targets.txt diff --git a/meson.build b/meson.build index 5b03e90c3db..0f086757e17 100644 --- a/meson.build +++ b/meson.build @@ -3330,6 +3330,13 @@ alias_target('testprep', testprep_targets) alias_target('world', all_built, docs) alias_target('install-world', install_quiet, installdocs) +run_target('help', + command: [ + perl, '-ne', 'next if /^#/; print', + files('doc/src/sgml/meson-targets.txt'), + ] +) + ############################################################### diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 49d35dd0d6e..28858f42228 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -110,6 +110,9 @@ keywords-table.sgml: $(top_srcdir)/src/include/parser/kwlist.h $(wildcard $(srcd wait_event_types.sgml: $(top_srcdir)/src/backend/utils/activity/wait_event_names.txt $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl $(PERL) $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl --docs $< +meson-targets.sgml: meson-targets.txt $(srcdir)/generate-meson-targets.pl + $(PERL) $(srcdir)/generate-meson-targets.pl $^ > $@ + ## ## Generation of some text files. ## diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 4c63a7e7689..ed89e75b614 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -38,6 +38,7 @@ + diff --git a/doc/src/sgml/generate-meson-targets.pl b/doc/src/sgml/generate-meson-targets.pl new file mode 100644 index 00000000000..65314aee282 --- /dev/null +++ b/doc/src/sgml/generate-meson-targets.pl @@ -0,0 +1,63 @@ +#!/usr/bin/perl +# +# Generate the meson-targets.sgml file from meson-targets.txt +# Copyright (c) 2000-2023, PostgreSQL Global Development Group + +use strict; +use warnings; + +my $meson_targets_file = $ARGV[0]; +open my $meson_targets, '<', $meson_targets_file or die; + +print + "\n"; + +# Find the start of each group of targets +while (<$meson_targets>) +{ + next if /^#/; + + if (/^(.*) Targets:$/) + { + my $targets = $1; + my $targets_id = lc $targets; + + print qq( + + $targets Targets + + +); + + # Each target in the group + while (<$meson_targets>) + { + next if /^#/; + last if !/^\s+([^ ]+)\s+(.+)/; + + my $target = $1; + my $desc = $2; + my $target_id = $1; + + $target_id =~ s/\//-/g; + + print qq( + + + + + ${desc} + + + +); + } + + print qq( + + +); + } +} + +close $meson_targets; diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 9dde19224a7..d7fefa0918c 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -3212,236 +3212,7 @@ ninja install target. - - Code Targets - - - - - - - - Build everything other than documentation - - - - - - - - - Build backend and related modules. - - - - - - - - - Build frontend binaries. - - - - - - - - - Build contrib modules. - - - - - - - - - Build procedual languages. - - - - - - - - - - Install Targets - - - - - - - - Install postgres, excluding documentation. - - - - - - - - - Like , but installed - files are not displayed. - - - - - - - - - Install postgres, including multi-page HTML and man page - documentation. - - - - - - - - - Install documentation in multi-page HTML and man page formats. See - also , . - - - - - - - - - Install documentation in multi-page HTML format. - - - - - - - - - Install documentation in man page format. - - - - - - - - - Remove installed files. - - - - - - - - - Documentation Targets - - - - - - - - - Build documentation in multi-page HTML format. Note that - does not include building - man page documentation, as man page generation seldom fails when - building HTML documentation succeeds. - - - - - - - - - Build documentation in man page format. - - - - - - - - - Build documentation in single-page HTML format. - - - - - - - - - - Build documentation in PDF format, using A4 and U.S. letter format - respectively. - - - - - - - - - Build documentation in all supported formats. Primarily useful when - testing larger documentation changes. - - - - - - - - - - Other Targets - - - - - - - - Remove all build products - - - - - - - - - Run all enabled tests (including contrib). Support for some classes - of tests can be enabled / disabled with and . - - - - - - - - - - Build everything, including documentation. - - - - - - - - + &meson-targets; diff --git a/doc/src/sgml/meson-targets.txt b/doc/src/sgml/meson-targets.txt new file mode 100644 index 00000000000..690e4ebc814 --- /dev/null +++ b/doc/src/sgml/meson-targets.txt @@ -0,0 +1,38 @@ +# Copyright (c) 2023, PostgreSQL Global Development Group +# +# Description of important meson targets, used for the 'help' target and +# installation.sgml (via generate-meson-targets.pl). Right now the parsers are +# extremely simple. Both parsers ignore comments. The help target prints +# everything else. For xml everything without a leading newline is a group, +# remaining lines are target separated by whitespace from their description +# +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 diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build index fac7e701610..2dca38ccf7b 100644 --- a/doc/src/sgml/meson.build +++ b/doc/src/sgml/meson.build @@ -71,6 +71,15 @@ doc_generated += custom_target('keywords-table.sgml', capture: true, ) +doc_generated += custom_target('meson-targets.sgml', + input: files('meson-targets.txt'), + output: 'meson-targets.sgml', + command: [perl, files('generate-meson-targets.pl'), '@INPUT@'], + build_by_default: false, + install: false, + capture: true, +) + # For everything else we need at least xmllint if not xmllint_bin.found() subdir_done() -- 2.38.0