Merge branch '1.7-release'

CHANGES

@@ -32,12 +32,17 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #4467: html theme: Rename ``csss`` block to ``css``
+
 Deprecated
 ----------
 
 Features added
 --------------
 
+* #4271: sphinx-build supports an option called ``-j auto`` to adjust numbers of
+  processes automatically.
+
 Bugs fixed
 ----------
 
@@ -221,6 +226,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
 --------

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

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:]))

sphinx/cmdline.py

@@ -12,6 +12,7 @@ from __future__ import print_function
 
 import argparse
 import os
+import multiprocessing
 import sys
 import traceback
 
@@ -82,6 +83,23 @@ def handle_exception(app, args, exception, stderr=sys.stderr):
                   file=stderr)
 
 
+def jobs_argument(value):
+    # 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
+    to cpu_count.
+    """
+    if value == 'auto':
+        return multiprocessing.cpu_count()
+    else:
+        jobs = int(value)
+        if jobs <= 0:
+            raise argparse.ArgumentTypeError('job number should be a positive number')
+        else:
+            return jobs
+
+
 def get_parser():
     # type: () -> argparse.ArgumentParser
     parser = argparse.ArgumentParser(
@@ -128,10 +146,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 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 '

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 \
+            if (node.tagname == 'footnote' or
-               node.tagname.startswith('desc_'):
+                    'refuri' in node or
+                    node.tagname.startswith('desc_')):
                 # ignore footnote labels, labels automatically generated from a
                 # link and object descriptions
                 continue

sphinx/themes/basic/layout.html

@@ -123,7 +123,7 @@
     {%- block htmltitle %}
     <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
     {%- endblock %}
-    {%- block csss %}
+    {%- block css %}
     {{- css() }}
     {%- endblock %}
     {%- if not embedded %}

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() }}
     <link rel="stylesheet" href="_static/print.css" type="text/css" />
 {%- endblock %}

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`

tests/roots/test-stylesheets/_templates/layout.html

@@ -1,5 +1,5 @@
 {% extends "!layout.html" %}
-{%- block csss %}
+{%- block css %}
   {{ super() }}
     <link rel="stylesheet" href="_static/more_persistent.css" type="text/css" />
     <link rel="stylesheet" href="_static/more_default.css" type="text/css" title="Default" />

tests/test_build_html.py

@@ -269,6 +269,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.'),

tests/test_build_html5.py

@@ -178,6 +178,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']", ''),

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)