[PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>

The setup() function of a Sphinx-extension can return a dictionary. This
is treated by Sphinx as metadata of the extension [1].

With metadata "parallel_read_safe = True" a extension is marked as
save for "parallel reading of source". This is needed if you want
build in parallel with N processes. E.g.:

  make SPHINXOPTS=-j4 htmldocs

will no longer log warnings like:

  WARNING: the foobar extension does not declare if it is safe for
  parallel reading, assuming it isn't - please ask the extension author
  to check and make it explicit.

Add metadata to extensions:

* kernel-doc
* flat-table
* kernel-include

[1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/sphinx/kernel-doc.py     | 8 ++++++++
 Documentation/sphinx/kernel_include.py | 7 +++++++
 Documentation/sphinx/rstFlatTable.py   | 6 ++++++
 3 files changed, 21 insertions(+)
 mode change 100644 => 100755 Documentation/sphinx/rstFlatTable.py

diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py
index f6920c0..d15e07f 100644
--- a/Documentation/sphinx/kernel-doc.py
+++ b/Documentation/sphinx/kernel-doc.py
@@ -39,6 +39,8 @@ from docutils.parsers.rst import directives
 from sphinx.util.compat import Directive
 from sphinx.ext.autodoc import AutodocReporter
 
+__version__  = '1.0'
+
 class KernelDocDirective(Directive):
     """Extract kernel-doc comments from the specified file"""
     required_argument = 1
@@ -139,3 +141,9 @@ def setup(app):
     app.add_config_value('kerneldoc_verbosity', 1, 'env')
 
     app.add_directive('kernel-doc', KernelDocDirective)
+
+    return dict(
+        version = __version__,
+        parallel_read_safe = True,
+        parallel_write_safe = True
+    )
diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py
index db57382..f523aa6 100755
--- a/Documentation/sphinx/kernel_include.py
+++ b/Documentation/sphinx/kernel_include.py
@@ -39,11 +39,18 @@ from docutils.parsers.rst import directives
 from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
 from docutils.parsers.rst.directives.misc import Include
 
+__version__  = '1.0'
+
 # ==============================================================================
 def setup(app):
 # ==============================================================================
 
     app.add_directive("kernel-include", KernelInclude)
+    return dict(
+        version = __version__,
+        parallel_read_safe = True,
+        parallel_write_safe = True
+    )
 
 # ==============================================================================
 class KernelInclude(Include):
diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py
old mode 100644
new mode 100755
index 26db852..55f2757
--- a/Documentation/sphinx/rstFlatTable.py
+++ b/Documentation/sphinx/rstFlatTable.py
@@ -73,6 +73,12 @@ def setup(app):
     roles.register_local_role('cspan', c_span)
     roles.register_local_role('rspan', r_span)
 
+    return dict(
+        version = __version__,
+        parallel_read_safe = True,
+        parallel_write_safe = True
+    )
+
 # ==============================================================================
 def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
 # ==============================================================================
-- 
2.7.4

Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Mauro Carvalho Chehab]

Em Wed, 24 Aug 2016 15:35:24 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> From: Markus Heiser <markus.heiser@darmarIT.de>
> 
> The setup() function of a Sphinx-extension can return a dictionary. This
> is treated by Sphinx as metadata of the extension [1].
> 
> With metadata "parallel_read_safe = True" a extension is marked as
> save for "parallel reading of source". This is needed if you want
> build in parallel with N processes. E.g.:
> 
>   make SPHINXOPTS=-j4 htmldocs
> 
> will no longer log warnings like:
> 
>   WARNING: the foobar extension does not declare if it is safe for
>   parallel reading, assuming it isn't - please ask the extension author
>   to check and make it explicit.
> 
> Add metadata to extensions:
> 
> * kernel-doc
> * flat-table
> * kernel-include
> 
> [1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata
> 
> Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>

Tested here on my desktop:

$ make cleandocs; time make SPHINXOPTS="-q" DOCBOOKS="" SPHINXDIRS=media SPHINX_CONF="conf.py" htmldocs
  SPHINX  htmldocs --> file:///devel/v4l/patchwork/Documentation/output/media;
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
  PARSE   include/uapi/linux/dvb/audio.h
  PARSE   include/uapi/linux/dvb/ca.h
  PARSE   include/uapi/linux/dvb/dmx.h
  PARSE   include/uapi/linux/dvb/frontend.h
  PARSE   include/uapi/linux/dvb/net.h
  PARSE   include/uapi/linux/dvb/video.h
  PARSE   include/uapi/linux/videodev2.h
  PARSE   include/uapi/linux/media.h
  PARSE   include/linux/cec.h
  PARSE   include/uapi/linux/lirc.h
load additional sphinx-config: /devel/v4l/patchwork/Documentation/media/conf.py
/devel/v4l/patchwork/Documentation/media/uapi/v4l/extended-controls.rst:2116: WARNING: Inline literal start-string without end-string.
/devel/v4l/patchwork/Documentation/media/uapi/v4l/extended-controls.rst:2116: WARNING: Inline literal start-string without end-string.
  SKIP    DocBook htmldocs target (DOCBOOKS="" specified).

real	0m55.837s
user	0m54.620s
sys	0m1.333s

$ make cleandocs; time make SPHINXOPTS="-q -j8" DOCBOOKS="" SPHINXDIRS=media SPHINX_CONF="conf.py" htmldocs
  SPHINX  htmldocs --> file:///devel/v4l/patchwork/Documentation/output/media;
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
  PARSE   include/uapi/linux/dvb/audio.h
  PARSE   include/uapi/linux/dvb/ca.h
  PARSE   include/uapi/linux/dvb/dmx.h
  PARSE   include/uapi/linux/dvb/frontend.h
  PARSE   include/uapi/linux/dvb/net.h
  PARSE   include/uapi/linux/dvb/video.h
  PARSE   include/uapi/linux/videodev2.h
  PARSE   include/uapi/linux/media.h
  PARSE   include/linux/cec.h
  PARSE   include/uapi/linux/lirc.h
load additional sphinx-config: /devel/v4l/patchwork/Documentation/media/conf.py
/devel/v4l/patchwork/Documentation/media/uapi/v4l/extended-controls.rst:2116: WARNING: Inline literal start-string without end-string.
/devel/v4l/patchwork/Documentation/media/uapi/v4l/extended-controls.rst:2116: WARNING: Inline literal start-string without end-string.
  SKIP    DocBook htmldocs target (DOCBOOKS="" specified).

real	0m22.340s
user	1m21.041s
sys	0m3.624s

Time reduced from 55 to 22 seconds. Sounds good enough!

Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

Thanks!
Mauro

PS: on my server with 16 dual-thread Xeon CPU, the gain with a
bigger value for -j was not impressive. Got about the same time as
with -j8 or -j32 there.

> ---
>  Documentation/sphinx/kernel-doc.py     | 8 ++++++++
>  Documentation/sphinx/kernel_include.py | 7 +++++++
>  Documentation/sphinx/rstFlatTable.py   | 6 ++++++
>  3 files changed, 21 insertions(+)
>  mode change 100644 => 100755 Documentation/sphinx/rstFlatTable.py
> 
> diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py
> index f6920c0..d15e07f 100644
> --- a/Documentation/sphinx/kernel-doc.py
> +++ b/Documentation/sphinx/kernel-doc.py
> @@ -39,6 +39,8 @@ from docutils.parsers.rst import directives
>  from sphinx.util.compat import Directive
>  from sphinx.ext.autodoc import AutodocReporter
>  
> +__version__  = '1.0'
> +
>  class KernelDocDirective(Directive):
>      """Extract kernel-doc comments from the specified file"""
>      required_argument = 1
> @@ -139,3 +141,9 @@ def setup(app):
>      app.add_config_value('kerneldoc_verbosity', 1, 'env')
>  
>      app.add_directive('kernel-doc', KernelDocDirective)
> +
> +    return dict(
> +        version = __version__,
> +        parallel_read_safe = True,
> +        parallel_write_safe = True
> +    )
> diff --git a/Documentation/sphinx/kernel_include.py b/Documentation/sphinx/kernel_include.py
> index db57382..f523aa6 100755
> --- a/Documentation/sphinx/kernel_include.py
> +++ b/Documentation/sphinx/kernel_include.py
> @@ -39,11 +39,18 @@ from docutils.parsers.rst import directives
>  from docutils.parsers.rst.directives.body import CodeBlock, NumberLines
>  from docutils.parsers.rst.directives.misc import Include
>  
> +__version__  = '1.0'
> +
>  # ==============================================================================
>  def setup(app):
>  # ==============================================================================
>  
>      app.add_directive("kernel-include", KernelInclude)
> +    return dict(
> +        version = __version__,
> +        parallel_read_safe = True,
> +        parallel_write_safe = True
> +    )
>  
>  # ==============================================================================
>  class KernelInclude(Include):
> diff --git a/Documentation/sphinx/rstFlatTable.py b/Documentation/sphinx/rstFlatTable.py
> old mode 100644
> new mode 100755
> index 26db852..55f2757
> --- a/Documentation/sphinx/rstFlatTable.py
> +++ b/Documentation/sphinx/rstFlatTable.py
> @@ -73,6 +73,12 @@ def setup(app):
>      roles.register_local_role('cspan', c_span)
>      roles.register_local_role('rspan', r_span)
>  
> +    return dict(
> +        version = __version__,
> +        parallel_read_safe = True,
> +        parallel_write_safe = True
> +    )
> +
>  # ==============================================================================
>  def c_span(name, rawtext, text, lineno, inliner, options=None, content=None):
>  # ==============================================================================



Thanks,
Mauro

Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Jonathan Corbet]

On Wed, 24 Aug 2016 15:35:24 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

> With metadata "parallel_read_safe = True" a extension is marked as
> save for "parallel reading of source". This is needed if you want
> build in parallel with N processes. E.g.:
> 
>   make SPHINXOPTS=-j4 htmldocs

A definite improvement; applied to the docs tree, thanks.

jon

Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Jani Nikula]

On Thu, 01 Sep 2016, Jonathan Corbet <corbet@lwn.net> wrote:
> On Wed, 24 Aug 2016 15:35:24 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
>
>> With metadata "parallel_read_safe = True" a extension is marked as
>> save for "parallel reading of source". This is needed if you want
>> build in parallel with N processes. E.g.:
>> 
>>   make SPHINXOPTS=-j4 htmldocs
>
> A definite improvement; applied to the docs tree, thanks.

The Sphinx docs say -jN "should be considered experimental" [1]. Any
idea *how* experimental that is, really? Could we add some -j by
default?

BR,
Jani.


[1] http://www.sphinx-doc.org/en/stable/invocation.html#invocation-of-sphinx-build

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Markus Heiser]

Am 01.09.2016 um 16:29 schrieb Jani Nikula <jani.nikula@linux.intel.com>:

> On Thu, 01 Sep 2016, Jonathan Corbet <corbet@lwn.net> wrote:
>> On Wed, 24 Aug 2016 15:35:24 +0200
>> Markus Heiser <markus.heiser@darmarit.de> wrote:
>> 
>>> With metadata "parallel_read_safe = True" a extension is marked as
>>> save for "parallel reading of source". This is needed if you want
>>> build in parallel with N processes. E.g.:
>>> 
>>>  make SPHINXOPTS=-j4 htmldocs
>> 
>> A definite improvement; applied to the docs tree, thanks.
> 
> The Sphinx docs say -jN "should be considered experimental" [1]. Any
> idea *how* experimental that is, really? Could we add some -j by
> default?

My experience is, that parallel build is only strong on "reading
input" and weak on "writing output". I can't see any rich performance
increase on more than -j2 ... 

Mauro posted [2] his experience with -j8 compared to serial. He
also compares -j8 to -j16:

> PS: on my server with 16 dual-thread Xeon CPU, the gain with a
> bigger value for -j was not impressive. Got about the same time as
> with -j8 or -j32 there.

I guess he will get nearly the same results with -j2 ;)

If we want to add a -j default, I suggest -j2. 

[2] https://www.mail-archive.com/linux-doc%40vger.kernel.org/msg05552.html

-- Markus --


> BR,
> Jani.
> 
> 
> [1] http://www.sphinx-doc.org/en/stable/invocation.html#invocation-of-sphinx-build
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center

Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Markus Heiser]

Am 01.09.2016 um 18:22 schrieb Markus Heiser <markus.heiser@darmarit.de>:

> 
> Am 01.09.2016 um 16:29 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
> 
>> On Thu, 01 Sep 2016, Jonathan Corbet <corbet@lwn.net> wrote:
>>> On Wed, 24 Aug 2016 15:35:24 +0200
>>> Markus Heiser <markus.heiser@darmarit.de> wrote:
>>> 
>>>> With metadata "parallel_read_safe = True" a extension is marked as
>>>> save for "parallel reading of source". This is needed if you want
>>>> build in parallel with N processes. E.g.:
>>>> 
>>>> make SPHINXOPTS=-j4 htmldocs
>>> 
>>> A definite improvement; applied to the docs tree, thanks.
>> 
>> The Sphinx docs say -jN "should be considered experimental" [1]. Any
>> idea *how* experimental that is, really? Could we add some -j by
>> default?
> 
> My experience is, that parallel build is only strong on "reading
> input" and weak on "writing output". I can't see any rich performance
> increase on more than -j2 ... 
> 
> Mauro posted [2] his experience with -j8 compared to serial. He
> also compares -j8 to -j16:
> 
>> PS: on my server with 16 dual-thread Xeon CPU, the gain with a
>> bigger value for -j was not impressive. Got about the same time as
>> with -j8 or -j32 there.
> 
> I guess he will get nearly the same results with -j2 ;)
> 
> If we want to add a -j default, I suggest -j2. 
> 
> [2] https://www.mail-archive.com/linux-doc%40vger.kernel.org/msg05552.html
> 
> -- Markus --
> 

Sorry, forget to mentioning, that there has been some improvements
to parallel build in Sphinx 1.3 compared to 1.2. But in 1.3.2 they
have also fixed a bug which lets parallel builds hang :-o

https://github.com/sphinx-doc/sphinx/blob/master/CHANGES#L665

This in mind and if we really support down to sphinx 1.2 ... we
should not use any -j default.

IMHO we should get rid of this sphinx 1.2. downward compatibility,
it makes so may problems (e.g. see [3]) ... but we have discussed
this already and I don't want to restart this thread ;-) 

[3] https://www.mail-archive.com/linux-doc%40vger.kernel.org/msg05695.html

-- Markus --



> 
>> BR,
>> Jani.
>> 
>> 
>> [1] http://www.sphinx-doc.org/en/stable/invocation.html#invocation-of-sphinx-build
>> 
>> -- 
>> Jani Nikula, Intel Open Source Technology Center
> 
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] doc-rst:sphinx-extensions: add metadata parallel-safe

[Mauro Carvalho Chehab]

Em Thu, 1 Sep 2016 18:22:09 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 01.09.2016 um 16:29 schrieb Jani Nikula <jani.nikula@linux.intel.com>:
> 
> > On Thu, 01 Sep 2016, Jonathan Corbet <corbet@lwn.net> wrote:  
> >> On Wed, 24 Aug 2016 15:35:24 +0200
> >> Markus Heiser <markus.heiser@darmarit.de> wrote:
> >>   
> >>> With metadata "parallel_read_safe = True" a extension is marked as
> >>> save for "parallel reading of source". This is needed if you want
> >>> build in parallel with N processes. E.g.:
> >>> 
> >>>  make SPHINXOPTS=-j4 htmldocs  
> >> 
> >> A definite improvement; applied to the docs tree, thanks.  
> > 
> > The Sphinx docs say -jN "should be considered experimental" [1]. Any
> > idea *how* experimental that is, really? Could we add some -j by
> > default?  
> 
> My experience is, that parallel build is only strong on "reading
> input" and weak on "writing output". I can't see any rich performance
> increase on more than -j2 ... 
> 
> Mauro posted [2] his experience with -j8 compared to serial. He
> also compares -j8 to -j16:
> 
> > PS: on my server with 16 dual-thread Xeon CPU, the gain with a
> > bigger value for -j was not impressive. Got about the same time as
> > with -j8 or -j32 there.  
> 
> I guess he will get nearly the same results with -j2 ;)
> 
> If we want to add a -j default, I suggest -j2. 

Actually, here I got better results with -j4, on my NUC with
one quad-core, 8 threads Intel(R) Core(TM) i7-6770HQ CPU @ 2.60GHz
and m2SATA SSD disk. 

This is with -j2:

$ make DOCBOOKS="" SPHINXOPTS="-j2" SPHINXDIRS=media SPHINX_CONF="conf_nitpick.py" htmldocs 2>err

real	0m46.568s
user	1m0.676s
sys	0m3.019s

And this is with -j4:

$ make DOCBOOKS="" SPHINXOPTS="-j4" SPHINXDIRS=media SPHINX_CONF="conf_nitpick.py" htmldocs 2>err

real	0m25.356s
user	1m1.408s
sys	0m2.912s

Btw, this is the result on a dual octa-core Intel(R) Xeon(R) CPU E5-2670 0 
@ 2.60GHz, CPU (total of 32 threads), using PCIe SSD disks:

$ for i in $(seq 32 -1 1); do echo "with SPHINXOPTS= -j$i"; make cleandocs;/usr/bin/time --format="real %E nuser %U sys %S" make DOCBOOKS=""  SPHINXOPTS="-j$i" SPHINXDIRS=media SPHINX_CONF="conf.py" SPHINXDIRS=media htmldocs >err; done
with SPHINXOPTS= -j32
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.05 nuser 98.77 sys 6.45
with SPHINXOPTS= -j31
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:22.81 nuser 97.80 sys 6.12
with SPHINXOPTS= -j30
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.16 nuser 97.68 sys 6.41
with SPHINXOPTS= -j29
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:22.74 nuser 98.02 sys 6.33
with SPHINXOPTS= -j28
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.18 nuser 95.75 sys 6.14
with SPHINXOPTS= -j27
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:22.67 nuser 96.66 sys 6.27
with SPHINXOPTS= -j26
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:22.66 nuser 95.93 sys 6.50
with SPHINXOPTS= -j25
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.71 nuser 95.43 sys 6.43
with SPHINXOPTS= -j24
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.71 nuser 94.27 sys 6.42
with SPHINXOPTS= -j23
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.46 nuser 93.85 sys 6.35
with SPHINXOPTS= -j22
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.28 nuser 91.52 sys 6.29
with SPHINXOPTS= -j21
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.93 nuser 90.37 sys 6.14
with SPHINXOPTS= -j20
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:24.88 nuser 91.40 sys 6.36
with SPHINXOPTS= -j19
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:24.00 nuser 89.68 sys 5.82
with SPHINXOPTS= -j18
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.73 nuser 89.68 sys 5.92
with SPHINXOPTS= -j17
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.75 nuser 87.85 sys 5.58
with SPHINXOPTS= -j16
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:24.54 nuser 87.87 sys 5.94
with SPHINXOPTS= -j15
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:25.45 nuser 88.25 sys 6.28
with SPHINXOPTS= -j14
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.79 nuser 87.23 sys 5.80
with SPHINXOPTS= -j13
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:24.15 nuser 86.06 sys 5.48
with SPHINXOPTS= -j12
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:24.02 nuser 85.94 sys 5.55
with SPHINXOPTS= -j11
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:23.79 nuser 85.12 sys 5.38
with SPHINXOPTS= -j10
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:25.37 nuser 85.32 sys 5.52
with SPHINXOPTS= -j9
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:26.04 nuser 86.96 sys 5.58
with SPHINXOPTS= -j8
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:26.76 nuser 86.38 sys 5.84
with SPHINXOPTS= -j7
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:27.90 nuser 85.33 sys 5.54
with SPHINXOPTS= -j6
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:28.44 nuser 84.59 sys 5.44
with SPHINXOPTS= -j5
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:31.82 nuser 83.98 sys 5.56
with SPHINXOPTS= -j4
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:35.68 nuser 83.98 sys 5.52
with SPHINXOPTS= -j3
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 0:43.00 nuser 85.08 sys 5.78
with SPHINXOPTS= -j2
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 1:10.72 nuser 88.61 sys 6.17
with SPHINXOPTS= -j1
make[2]: warning: jobserver unavailable: using -j1.  Add '+' to parent make rule.
real 1:27.23 nuser 84.49 sys 2.97

There, -j4 is not the best performance. it goes to the ~23-24 seconds only
with -j11.

So, setting a default is not trivial, and seems to depend a lot on the
actual machine used on the build.

Regards,
Mauro