Re: [PATCH] docs: Prefer 'python3' when building htmldocs

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Thu, 19 Mar 2020 16:00:42 -0700
Victor Erminpour <victor.erminpour@oracle.com> escreveu:

> Prefer 'python3' and 'sphinx-build-3' when building htmldocs.
> Building htmldocs fails on systems that don't have 'python'
> and 'sphinx-build' installed, but do have 'python3' and
> 'sphinx-build-3' available.
> 
> Signed-off-by: Victor Erminpour <victor.erminpour@oracle.com>
> ---
>  Documentation/Makefile | 15 ++++++++++++++-
>  1 file changed, 14 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index d77bb607aea4..00c400523e15 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -11,6 +11,7 @@ endif
>  
>  # You can set these variables from the command line.
>  SPHINXBUILD   = sphinx-build
> +SPHINXBUILD3  = sphinx-build-3

This will very likely break on some distros. For example, Fedora 31 with a
venv configured environment won't have a "sphinx-build-3" program. 

I have already a patchset addressing this. I'm testing it on several
different distros and versions.

My plan is to submit the patch series for it after the merge window. If you
want to do a sneak pick, there's a version of the patch series on my
experimental tree (probably not the latest version):

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=random_doc_fixes


>  SPHINXOPTS    =
>  SPHINXDIRS    = .
>  _SPHINXDIRS   = $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst))
> @@ -61,11 +62,23 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
>  # $5 reST source folder relative to $(srctree)/$(src),
>  #    e.g. "media" for the linux-tv book-set at ./Documentation/media
>  
> +HAVE_PYTHON3 := $(shell if which $(PYTHON3) >/dev/null 2>&1; then echo 1; else echo 0; fi)
> +HAVE_SPHINX3 := $(shell if which $(SPHINXBUILD3) >/dev/null 2>&1; then echo 1; else echo 0; fi)
> +PYTHON_BIN = $(PYTHON)
> +
> +# If we have both python3 and sphinx-build-3,
> +# prefer python3 over python.
> +ifeq ($(HAVE_PYTHON3),1)
> +    ifeq ($(HAVE_SPHINX3),1)
> +        PYTHON_BIN = $(PYTHON3)
> +    endif
> +endif
> +
>  quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
>        cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
>  	PYTHONDONTWRITEBYTECODE=1 \
>  	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
> -	$(PYTHON) $(srctree)/scripts/jobserver-exec \
> +	$(PYTHON_BIN) $(srctree)/scripts/jobserver-exec \
>  	$(SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \
>  	$(SPHINXBUILD) \
>  	-b $2 \



Thanks,
Mauro