Re: meson documentation build open issues

Hi,

On 2023-11-06 10:45:27 +0100, Christoph Berg wrote:
> Re: Andres Freund
> > > > The reason for that is simply that the docs take too long to build.
> > >
> > > That why I'd prefer to be able to separate arch:all and arch:any
> > > builds, yes.
> > 
> > What's stopping you from doing that?  I think the only arch:any content we
> > have is the docs, and those you can build separately? Doc builds do trigger
> > generation of a handful of files besides the docs, but not more.
> 
> Historically, .deb files have been required to contain the manpages
> for all executables even when there's a separate -doc package. This
> means we'd need a separate (hopefully fast) manpage build even when
> the arch:any binaries are built.

Manpages are a bit faster to build than html, but not a whole lot. Both are a
lot faster than PDF.


> We might get around that by introducing a new postgresql-manpages-XX
> arch:all package, but that might be too much micropackaging.

I've not done packaging in, uh, a fair while, but isn't the common solution to
that a -common package? There might be a few more files we could put itno one.


> > +     <varlistentry id="configure-with-sepgsql-meson">
> > +      <term><option>-Dselinux={ disabled | auto | enabled }</option></term>
> > +      <listitem>
> > +       <para>
> > +        Build with selinux support, enabling the <xref linkend="sepgsql"/>
> > +        extension.
> 
> This option defaults to ... auto?

Not quite sure what you mean? Today it defaults to disabled, a patch changing
that should also change the docs?


> > index 90e2c062fa8..003b57498bb 100644
> > --- a/doc/src/sgml/meson.build
> > +++ b/doc/src/sgml/meson.build
> > @@ -142,6 +142,7 @@ if docs_dep.found()
> >        '--install-dir-contents', dir_doc_html, html],
> >      build_always_stale: true, build_by_default: false,
> >    )
> > +  alias_target('doc-html', install_doc_html)
> >    alias_target('install-doc-html', install_doc_html)
> 
> Shouldn't this just build the html docs, without installing?
> 
> > +  alias_target('doc-man', install_doc_html)
> >    alias_target('install-doc-man', install_doc_man)
> 
> ... same
> 
> 
> > +     <varlistentry id="meson-target-install-world">
> > +       <term><option>install-install-world</option></term>
> 
> install-world
> 
> > +     <varlistentry id="meson-target-install-doc-man">
> > +       <term><option>install-doc-html</option></term>
> > +       <listitem>
> > +        <para>
> > +         Install documentation in man page format.
> 
> install-doc-man

Oops.


> > +   <sect3 id="meson-targets-docs">
> > +    <title>Documentation Targets</title>
> 
> > +     <varlistentry id="meson-target-docs">
> > +       <term><option>docs</option></term>
> > +       <term><option>doc-html</option></term>
> > +       <listitem>
> > +        <para>
> > +         Build documentation in multi-page HTML format.  Note that
> > +         <option>docs</option> does <emphasis>not</emphasis> include building
> > +         man page documentation, as man page generation seldom fails when
> > +         building HTML documentation succeeds.
> 
> Why is that a reason for not building the manpages?

I didn't have it that way, and Tom argued strongly for maintaining that
behaviour from the make build. Personally I wouldn't.



> > +   <sect3 id="meson-targets-code">
> > +    <title>Code Targets</title>
> 
> I would have expected the sections to be in the order
> build-docs-install. Having install first seems weird to me.

Makes sense to me. I just had the install first because I wrote it first
because of our conversation...


> > +   <sect3 id="meson-targets-other">
> > +    <title>Other Targets</title>
> > +
> > +    <variablelist>
> > +
> > +     <varlistentry id="meson-target-clean">
> > +       <term><option>clean</option></term>
> > +       <listitem>
> > +        <para>
> > +         Remove all build products
> > +        </para>
> > +       </listitem>
> > +     </varlistentry>
> > +
> > +     <varlistentry id="meson-target-test">
> > +       <term><option>test</option></term>
> > +       <listitem>
> > +        <para>
> > +         Remove all enabled tests. Support for some classes of tests can be
> > +         enabled / disabled with <xref linkend="configure-tap-tests-meson"/>
> > +         and <xref linkend="configure-pg-test-extra-meson"/>.
> 
> This should explicitly say if contrib tests are included (or there
> needs to be a separate test-world target.)

They are included, will state that. And also s/Remove/Run/


> > Subject: [PATCH v1 5/5] meson: Add -Dpkglibdir option
> 
> Will give that a try, thanks!

Thanks for the review!

Greetings,

Andres Freund