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: Peter Eisentraut <peter@eisentraut.org>
Cc: Christoph Berg <myon@debian.org>, Andrew Dunstan <andrew@dunslane.net>, Tom Lane <tgl@sss.pgh.pa.us>, pgsql-hackers <pgsql-hackers@postgresql.org>
Date: 2023-11-17T18:53:06Z
Lists: pgsql-hackers

Attachments

Hi,

On 2023-11-14 16:30:24 -0800, Andres Freund wrote:
> On 2023-11-14 16:22:31 -0800, Andres Freund wrote:
> > > v2-0004-meson-Add-world-target.patch
> > > 
> > > AFAICT, this world target doesn't include the man target.  (Again, this
> > > would all work better if we added "man" to "docs".)
> > 
> > I agree with that sentiment - I only moved to the current arrangement after
> > Tom argued forcefully against building both.
> 
> Another message in this thread made me realize that I actually hadn't
> implemented it at all - it was Tom in 969509c3f2e
> 
>     In HEAD, also document how to build docs using Meson, and adjust
>     "ninja docs" to just build the HTML docs, for consistency with the
>     default behavior of doc/src/sgml/Makefile.
> 
> 
> I think that change was just ill-advised, given that the top-level make target
> actually *does* build both html and man:
> 
> > The situation in the make world is weird:
> > "make docs" in the toplevel builds both, because it's defined as
> > 
> > docs:
> > 	$(MAKE) -C doc all
> 
> Notwithstanding this:
> 
> > Buf if you "make -C doc/src/sgml" (or are in doc/src/sgml), we only build
> > html, as the default target is explicitly just html:
> 
> As the obvious thing for people that really just want to build html with ninja
> would be to just use the doc-html (to-be-renamed to "html") target.

I pushed the first two commits (the selinux stuff) and worked a bit more on
the subsequent ones.

- As requested, I've renamed the 'doc-html' and 'doc-man' targets to just 'html'
  and 'man'. Which then seems to also necessitates renaming the existing
  install-doc-{html,man}.  I'm not so sure about this change, likely because I
  use autocomplete to remember the spelling of ninja (or make) targets, which
  is easier with [install-]doc-{html,man} than with [install-]{html,man}.

- I added a commit to change what 'docs' builds, undoing that part of
  969509c3f2e. I also moved the 'all' target in doc/src/sgml/Makefile up to
  the 'html' target to make things less confusing there, as discussed in the
  thread referenced in the commit message.

  Because of the 'html' target, Tom can still just build html easily.

- I renamed 'meson-targets.txt' to 'targets-meson.txt' and renamed other files
  to match. One reason is that meson tries to prevent conflict between its
  internal targets by prefixing them with 'meson-', and the old names
  conflicted with that rule. If we ever wanted to add something similar for
  make, the new naming also seems better.

- I added documentation for some developer targets (reformat-dat-files,
  expand-dat-files, update-unicode)

I didn't move 'world' in the docs, as it doesn't quite seem right in the "code
targets" section?


I attached the pkglibdir thing again, even though I don't plan to push it or
really review it further. Thought it might still be interesting for Christoph.

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