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@enterprisedb.com>
Cc: pgsql-hackers <pgsql-hackers@postgresql.org>
Date: 2023-03-22T18:59:17Z
Lists: pgsql-hackers 
Hi,

On 2023-03-20 10:32:49 -0700, Andres Freund wrote:
> On 2023-03-20 11:58:08 +0100, Peter Eisentraut wrote:
> > Oh, this patch set grew quite quickly. ;-)
> 
> Yep :)

Unless somebody sees a reason to wait, I am planning to commit:
  meson: add install-{quiet, world} targets
  meson: add install-{docs,doc-html,doc-man} targets
  meson: make install_test_files more generic, rename to install_files

While I don't think we have necessarily the path forward around .css and .svg,
the above are independent of that.


For the .svg: I wonder if we should just inline the images in the chunked
html, just like we do in the single page one. It's not like we reuse one image
across a lot of pages, so there's no bandwidth saved from having the images
separate...

For the .css: docbook-xsl actually has support for writing the .css: [1] - but
it requires the .css file be valid xml. I wonder if the cleanest approch would
be to have a build step to create .css.xml - then the non-chunked build's
generate.css.header would do the right thing.


I'll start a new thread for
  docs: speed up docs build by special-casing the gentext.template
  VERY WIP: parallel doc generation
after the feature freeze.


After looking into it a tiny bit more, it seems we should use neither pandoc
nor dbtoepub for epub generation.

All the dbtoepub does is to invoke the docbook-xsl support for epubs and zip
the result - except it doesn't use our stylesheets, so it looks randomly
different and doesn't use our speedups. At the very least we should use our
customizations, if we want epub support. Or we should just remove it.

Pandoc unfortunately doesn't do docbook well enough to be usable for now to
directly parse our docbook.

Regards,

Andres

[1] https://docbook.sourceforge.net/release/xsl/current/doc/html/custom.css.source.html

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