Re: [PATCH v3] meson: Pass -j option to sphinx

[Markus Armbruster]

Fabiano Rosas <farosas@suse.de> writes:

> Save a bit of build time by passing the number of jobs option to
> sphinx.
>
> We cannot use the -j option from make because meson does not support
> setting build time parameters for custom targets. Use nproc instead or
> the equivalent sphinx option "-j auto", if that is available.
>
> Also make sure our plugins support parallelism and report it properly
> to sphinx. Particularly, implement the merge_domaindata method in
> DBusDomain that is used to merge in data from other subprocesses.
>
> before:
>   $ time make man html
>   ...
>   [1/2] Generating docs/QEMU manual with a custom command
>   [2/2] Generating docs/QEMU man pages with a custom command
>
>   real    0m43.157s
>   user    0m42.642s
>   sys     0m0.576s
>
> after:
>   $ time make man html
>   ...
>   [1/2] Generating docs/QEMU manual with a custom command
>   [2/2] Generating docs/QEMU man pages with a custom command
>
>   real    0m25.014s
>   user    0m51.288s
>   sys     0m2.085s

Thanks for tackling this!  sphinx-build is so slow I disable doc
building unless I'm working on docs.

> Tested-by: Daniel P. Berrangé <berrange@redhat.com>
> Signed-off-by: Fabiano Rosas <farosas@suse.de>
> ---
>  docs/meson.build           | 12 ++++++++++++
>  docs/sphinx/dbusdomain.py  |  4 ++++
>  docs/sphinx/fakedbusdoc.py |  5 +++++
>  docs/sphinx/qmp_lexer.py   |  5 +++++
>  4 files changed, 26 insertions(+)
>
> diff --git a/docs/meson.build b/docs/meson.build
> index f220800e3e..138ec6ce6f 100644
> --- a/docs/meson.build
> +++ b/docs/meson.build
> @@ -10,6 +10,18 @@ if sphinx_build.found()
>      SPHINX_ARGS += [ '-W', '-Dkerneldoc_werror=1' ]
>    endif
>  
> +  sphinx_version = run_command(SPHINX_ARGS + ['--version'],
> +                               check: true).stdout().split()[1]
> +  if sphinx_version.version_compare('>=5.1.2')

Where do you get 5.1.2 from?  I have 5.0.2, and -j auto appears to work
fine.  The manual page says "Changed in version 1.7: Support auto
argument."

> +    SPHINX_ARGS += ['-j', 'auto']
> +  else
> +    nproc = find_program('nproc')
> +    if nproc.found()
> +      jobs = run_command(nproc, check: true).stdout()
> +      SPHINX_ARGS += ['-j', jobs]
> +    endif
> +  endif
> +
>    # This is a bit awkward but works: create a trivial document and
>    # try to run it with our configuration file (which enforces a
>    # version requirement). This will fail if sphinx-build is too old.

[...]