From 1db38e0eca560b59a8276c4a80efd9e42483ffff Mon Sep 17 00:00:00 2001 From: mark floyd Date: Fri, 1 Dec 2017 18:34:33 -0800 Subject: [PATCH 01/13] sphinx-build: Add support for "-j auto" Adjust -j argument so it can accept special keyword "auto", which will set -j to the number of CPUs on machine. Change was inspired by headaches while trying to find the best way to get sphinx-build to use the max number of cores from any machine we build on (Ubuntu, Mac, AWS Linux, etc). Rather than write external scripts to set this (sysctl calls, grepping /proc/cpuinfo, etc), it made more sense to build the functionality into sphinx-build itself. Change Summary: * New custom type in sphinx.cmdline for handling -j argument * Adjusted help string for -j flag --- sphinx/cmdline.py | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 11f1861d8..590aa8b0a 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -11,6 +11,7 @@ from __future__ import print_function import argparse +import multiprocessing import sys import traceback from os import path @@ -83,6 +84,19 @@ def handle_exception(app, args, exception, stderr=sys.stderr): file=stderr) +def jobs_argument(value): + # type (int, str) -> int + """ + Special type to handle 'auto' flags passed to 'sphinx-build' via -j flag. Can + be expanded to handle other special scaling requests, such as setting job count + to (cpu_count / 2) + """ + if value == 'auto': + return multiprocessing.cpu_count() + else: + return value + + def get_parser(): # type: () -> argparse.ArgumentParser parser = argparse.ArgumentParser( @@ -129,10 +143,9 @@ files can be built by specifying individual filenames. group.add_argument('-d', metavar='PATH', dest='doctreedir', help='path for the cached environment and doctree ' 'files (default: OUTPUTDIR/.doctrees)') - group.add_argument('-j', metavar='N', default=1, type=int, dest='jobs', + group.add_argument('-j', metavar='N', default=1, type=jobs_argument, dest='jobs', help='build in parallel with N processes where ' - 'possible') - + 'possible (special value "auto" will set N to number of CPUs') group = parser.add_argument_group('build configuration options') group.add_argument('-c', metavar='PATH', dest='confdir', help='path where configuration file (conf.py) is ' From 19efb4a39810f1035d9d891f26154c74c6b54a89 Mon Sep 17 00:00:00 2001 From: mark floyd Date: Fri, 1 Dec 2017 18:52:46 -0800 Subject: [PATCH 02/13] Fixing typo in help string --- sphinx/cmdline.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 590aa8b0a..55b0cec98 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -145,7 +145,7 @@ files can be built by specifying individual filenames. 'files (default: OUTPUTDIR/.doctrees)') group.add_argument('-j', metavar='N', default=1, type=jobs_argument, dest='jobs', help='build in parallel with N processes where ' - 'possible (special value "auto" will set N to number of CPUs') + 'possible (special value "auto" will set N to cpu-count)') group = parser.add_argument_group('build configuration options') group.add_argument('-c', metavar='PATH', dest='confdir', help='path where configuration file (conf.py) is ' From 9c1bbf19488f6bd9c1261b87fcc0a10002d642a4 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 13 Jan 2018 15:44:56 +0900 Subject: [PATCH 03/13] Fix jobs_argument() should accept string as an argument --- sphinx/cmdline.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 310760d24..c2668065d 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -85,7 +85,7 @@ def handle_exception(app, args, exception, stderr=sys.stderr): def jobs_argument(value): - # type (int, str) -> int + # type: (str) -> int """ Special type to handle 'auto' flags passed to 'sphinx-build' via -j flag. Can be expanded to handle other special scaling requests, such as setting job count @@ -94,7 +94,7 @@ def jobs_argument(value): if value == 'auto': return multiprocessing.cpu_count() else: - return value + return int(value) def get_parser(): From 840b5828e752f4d19d2c569ea4299dcc17c506e3 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 13 Jan 2018 15:50:26 +0900 Subject: [PATCH 04/13] docs: Add ``-j auto`` option --- doc/man/sphinx-build.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index 46f213989..fdd0d36c2 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -143,11 +143,15 @@ Options Distribute the build over *N* processes in parallel, to make building on multiprocessor machines more effective. Note that not all parts and not all - builders of Sphinx can be parallelized. + builders of Sphinx can be parallelized. If ``auto`` argument is given, + Sphinx uses the number of CPUs as *N*. .. versionadded:: 1.2 This option should be considered *experimental*. + .. versionchanged:: 1.7 + Support ``auto`` argument. + .. option:: -c path Don't look for the :file:`conf.py` in the source directory, but use the given From f8dec554476c17510208e0fe08956b759cc76d9c Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 13 Jan 2018 15:53:15 +0900 Subject: [PATCH 05/13] Update docstring --- sphinx/cmdline.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index c2668065d..365238607 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -89,7 +89,7 @@ def jobs_argument(value): """ Special type to handle 'auto' flags passed to 'sphinx-build' via -j flag. Can be expanded to handle other special scaling requests, such as setting job count - to (cpu_count / 2) + to cpu_count. """ if value == 'auto': return multiprocessing.cpu_count() From ac200ecf7cfd1854fe4ce2e937c13f405ec65d19 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 13 Jan 2018 18:27:08 +0900 Subject: [PATCH 06/13] Update CHANGES --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index 39733a6d8..b91062f68 100644 --- a/CHANGES +++ b/CHANGES @@ -75,6 +75,8 @@ Features added * #4183: doctest: ``:pyversion:`` option also follows PEP-440 specification * #4235: html: Add :confval:`manpages_url` to make manpage roles to hyperlinks * #3570: autodoc: Do not display 'typing.' module for type hints +* #4271: sphinx-build supports an option called ``-j auto`` to adjust numbers of + processes automatically. Features removed ---------------- From ddcb45dad608c2d93c4a1da9fa17a0d27645e3ab Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 16 Jan 2018 01:03:53 +0900 Subject: [PATCH 07/13] Validate -j option is positive --- sphinx/cmdline.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 365238607..4cf5a07ef 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -94,7 +94,11 @@ def jobs_argument(value): if value == 'auto': return multiprocessing.cpu_count() else: - return int(value) + jobs = int(value) + if jobs <= 0: + raise argparse.ArgumentTypeError('job number should be a positive number') + else: + return jobs def get_parser(): From 896ab3a2f5abbc5868a9346084627361d6b56f8c Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 20 Jan 2018 17:06:56 +0900 Subject: [PATCH 08/13] Fix #4434: pure numbers as link targets produce warning --- CHANGES | 1 + sphinx/domains/std.py | 5 +++-- tests/roots/test-root/markup.txt | 2 ++ tests/test_build_html.py | 2 ++ tests/test_build_html5.py | 2 ++ tests/test_build_latex.py | 8 ++++---- 6 files changed, 14 insertions(+), 6 deletions(-) diff --git a/CHANGES b/CHANGES index 70c9f53c0..1d9a5fa82 100644 --- a/CHANGES +++ b/CHANGES @@ -20,6 +20,7 @@ Bugs fixed * #4412: Updated jQuery version from 3.1.0 to 3.2.1 * #4438: math: math with labels with whitespace cause html error * #2437: make full reference for classes, aliased with "alias of" +* #4434: pure numbers as link targets produce warning Testing -------- diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index 68baa04aa..a26109076 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -607,8 +607,9 @@ class StandardDomain(Domain): if node.tagname == 'target' and 'refid' in node: # indirect hyperlink targets node = document.ids.get(node['refid']) labelid = node['names'][0] - if name.isdigit() or 'refuri' in node or \ - node.tagname.startswith('desc_'): + if (node.tagname == 'footnote' or + 'refuri' in node or + node.tagname.startswith('desc_')): # ignore footnote labels, labels automatically generated from a # link and object descriptions continue diff --git a/tests/roots/test-root/markup.txt b/tests/roots/test-root/markup.txt index b514b3587..e6adef55e 100644 --- a/tests/roots/test-root/markup.txt +++ b/tests/roots/test-root/markup.txt @@ -1,6 +1,7 @@ :tocdepth: 2 .. title:: set by title directive +.. _1024: Testing various markup ====================== @@ -152,6 +153,7 @@ Adding \n to test unescaping. * :ref:`my-table-name` * :ref:`my-code-block` * :ref:`my-code-block-name` +* :ref:`1024` * :numref:`my-figure` * :numref:`my-figure-name` * :numref:`my-table` diff --git a/tests/test_build_html.py b/tests/test_build_html.py index 6fc024d35..bf9cc7f14 100644 --- a/tests/test_build_html.py +++ b/tests/test_build_html.py @@ -270,6 +270,8 @@ def test_html_warnings(app, warning): # tests for ``any`` role (".//a[@href='#with']/span", 'headings'), (".//a[@href='objects.html#func_without_body']/code/span", 'objects'), + # tests for numeric labels + (".//a[@href='#id1'][@class='reference internal']/span", 'Testing various markup'), # tests for smartypants (".//li", u'Smart “quotes” in English ‘text’.'), (".//li", u'Smart — long and – short dashes.'), diff --git a/tests/test_build_html5.py b/tests/test_build_html5.py index 217050ec7..f489a8b2f 100644 --- a/tests/test_build_html5.py +++ b/tests/test_build_html5.py @@ -179,6 +179,8 @@ def cached_etree_parse(): # tests for ``any`` role (".//a[@href='#with']/span", 'headings'), (".//a[@href='objects.html#func_without_body']/code/span", 'objects'), + # tests for numeric labels + (".//a[@href='#id1'][@class='reference internal']/span", 'Testing various markup'), ], 'objects.html': [ (".//dt[@id='mod.Cls.meth1']", ''), diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index 1ba115092..c23f50c65 100644 --- a/tests/test_build_latex.py +++ b/tests/test_build_latex.py @@ -130,24 +130,24 @@ def test_writer(app, status, warning): assert ('\\begin{sphinxfigure-in-table}\n\\centering\n\\capstart\n' '\\noindent\\sphinxincludegraphics{{img}.png}\n' - '\\sphinxfigcaption{figure in table}\\label{\\detokenize{markup:id7}}' + '\\sphinxfigcaption{figure in table}\\label{\\detokenize{markup:id8}}' '\\end{sphinxfigure-in-table}\\relax' in result) assert ('\\begin{wrapfigure}{r}{0pt}\n\\centering\n' '\\noindent\\sphinxincludegraphics{{rimg}.png}\n' - '\\caption{figure with align option}\\label{\\detokenize{markup:id8}}' + '\\caption{figure with align option}\\label{\\detokenize{markup:id9}}' '\\end{wrapfigure}' in result) assert ('\\begin{wrapfigure}{r}{0.500\\linewidth}\n\\centering\n' '\\noindent\\sphinxincludegraphics{{rimg}.png}\n' '\\caption{figure with align \\& figwidth option}' - '\\label{\\detokenize{markup:id9}}' + '\\label{\\detokenize{markup:id10}}' '\\end{wrapfigure}' in result) assert ('\\begin{wrapfigure}{r}{3cm}\n\\centering\n' '\\noindent\\sphinxincludegraphics[width=3cm]{{rimg}.png}\n' '\\caption{figure with align \\& width option}' - '\\label{\\detokenize{markup:id10}}' + '\\label{\\detokenize{markup:id11}}' '\\end{wrapfigure}' in result) From ecbe08d4679cc5af5971f6ed7d011b678af0d5f1 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sat, 20 Jan 2018 23:16:42 +0000 Subject: [PATCH 09/13] sphinx: Call 'sphinx.cmd.build.main' function This was missed in commit '89f9c7cab'. Signed-off-by: Stephen Finucane Fixes: #4470 --- sphinx/__main__.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sphinx/__main__.py b/sphinx/__main__.py index fbac1c4f7..47a183d08 100644 --- a/sphinx/__main__.py +++ b/sphinx/__main__.py @@ -8,7 +8,9 @@ :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ + import sys -from sphinx import main + +from sphinx.cmd.build import main sys.exit(main(sys.argv[1:])) From ade1a49ed1736217780ed256a5b29f3ffb37452a Mon Sep 17 00:00:00 2001 From: Aaron Carlisle Date: Sat, 20 Jan 2018 11:18:33 -0500 Subject: [PATCH 10/13] Themes: Rename 'csss' block to 'css' Was a mistake in 618ef6492c89c50f263c4c6c5794e40e35f91be8 --- sphinx/themes/basic/layout.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index dc05e980d..fe8829b77 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -123,7 +123,7 @@ {%- block htmltitle %} {{ title|striptags|e }}{{ titlesuffix }} {%- endblock %} - {%- block csss %} + {%- block css %} {{- css() }} {%- endblock %} {%- if not embedded %} From ccd70c3b896f29389cd2fb0f1b80fb9ae5cf9ed3 Mon Sep 17 00:00:00 2001 From: Aaron Carlisle Date: Sat, 20 Jan 2018 11:28:16 -0500 Subject: [PATCH 11/13] Update scrolls theme --- sphinx/themes/scrolls/layout.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/themes/scrolls/layout.html b/sphinx/themes/scrolls/layout.html index 9ebe3b35d..7ed27edf7 100644 --- a/sphinx/themes/scrolls/layout.html +++ b/sphinx/themes/scrolls/layout.html @@ -10,7 +10,7 @@ #} {%- extends "basic/layout.html" %} {% set script_files = script_files + ['_static/theme_extras.js'] %} -{%- block csss %} +{%- block css %} {{ super() }} {%- endblock %} From e77ca751033193da8c6507710ed346ae8ad20b1d Mon Sep 17 00:00:00 2001 From: Aaron Carlisle Date: Sat, 20 Jan 2018 11:29:22 -0500 Subject: [PATCH 12/13] Update test file --- tests/roots/test-stylesheets/_templates/layout.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/roots/test-stylesheets/_templates/layout.html b/tests/roots/test-stylesheets/_templates/layout.html index f9e5a2bc9..d048fe4af 100644 --- a/tests/roots/test-stylesheets/_templates/layout.html +++ b/tests/roots/test-stylesheets/_templates/layout.html @@ -1,5 +1,5 @@ {% extends "!layout.html" %} -{%- block csss %} +{%- block css %} {{ super() }} From a924fc13b4bee363d6e000768a841b5cf84c71c2 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 21 Jan 2018 13:20:16 +0900 Subject: [PATCH 13/13] Update CHANGES for PR #4467 --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index d5d0026fa..e06a6faba 100644 --- a/CHANGES +++ b/CHANGES @@ -7,6 +7,8 @@ Dependencies Incompatible changes -------------------- +* #4467: html theme: Rename ``csss`` block to ``css`` + Deprecated ----------