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

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

[Victor Erminpour]

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
 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 \

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

[Mauro Carvalho Chehab]

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

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

[Victor Erminpour]

On 3/20/20 4:15 AM, Mauro Carvalho Chehab wrote:
> 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.
>

Hi Mauro,

Fair enough, I've noticed that some distros provide a symlink from
sphinx-build to sphinx-build-3, but it's not guaranteed for every
distro (if they have python3 at all).


> 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://urldefense.com/v3/__https://git.linuxtv.org/mchehab/experimental.git/log/?h=random_doc_fixes__;!!GqivPVa7Brio!NJwqcbN8vCCZcaL8CGkgL27pxL0x4qCMpoQm6riFdb0Jo9_KuD6vROdjw_4owcdvncvO$
> 

Valeu, aquele abraço!

--Victor


> 
>>   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
> 

-- 
Victor Hugo Erminpour
Principal Member of Technical Staff
Oracle America