Merge branch 'stable'

Conflicts:
	sphinx/apidoc.py
	sphinx/application.py
	sphinx/quickstart.py

	modified:   CHANGES
	modified:   doc/config.rst
	modified:   doc/markup/inline.rst
	modified:   sphinx/application.py
	modified:   sphinx/builders/__init__.py
	modified:   sphinx/cmd/quickstart.py
	modified:   sphinx/ext/apidoc.py

CHANGES

@@ -131,6 +131,7 @@ Bugs fixed
 * #4279: Sphinx crashes with pickling error when run with multiple processes and
   remote image
 * #1421: Respect the quiet flag in sphinx-quickstart
+* #4281: Race conditions when creating output directory
 
 Testing
 --------

doc/config.rst

@@ -315,8 +315,8 @@ General configuration
 .. confval:: numfig
 
    If true, figures, tables and code-blocks are automatically numbered if they
-   have a caption.  At same time, the `numref` role is enabled.  For now, it
+   have a caption.  The :rst:role:`numref` role is enabled.
-   works only with the HTML builder and LaTeX builder. Default is ``False``.
+   Obeyed so far only by HTML and LaTeX builders. Default is ``False``.
 
    .. note::
 
@@ -339,10 +339,21 @@ General configuration
 
 .. confval:: numfig_secnum_depth
 
-   The scope of figure numbers, that is, the numfig feature numbers figures
+   - if set to ``0``, figures, tables and code-blocks are continuously numbered
-   in which scope. ``0`` means "whole document". ``1`` means "in a section".
+     starting at ``1``.
-   Sphinx numbers like x.1, x.2, x.3... ``2`` means "in a subsection". Sphinx
+   - if ``1`` (default) numbers will be ``x.1``, ``x.2``, ... with ``x``
-   numbers like x.x.1, x.x.2, x.x.3..., and so on. Default is ``1``.
+     the section number (top level sectioning; no ``x.`` if no section).
+     This naturally applies only if  section numbering has been activated via
+     the ``:numbered:`` option of the :rst:dir:`toctree` directive.
+   - ``2`` means that numbers will be ``x.y.1``, ``x.y.2``, ... if located in
+     a sub-section (but still ``x.1``, ``x.2``, ... if located directly under a
+     section and ``1``, ``2``, ... if not in any top level section.)
+   - etc...
+
+   .. note::
+
+      The LaTeX builder currently ignores this configuration setting. It will
+      obey it at Sphinx 1.7.
 
    .. versionadded:: 1.3
 

doc/markup/inline.rst

@@ -227,15 +227,15 @@ Cross-referencing figures by figure number
    reST labels are used.  When you use this role, it will insert a reference to
    the figure with link text by its figure number like "Fig. 1.1".
 
-   If an explicit link text is given (like usual: ``:numref:`Image of Sphinx (Fig.
+   If an explicit link text is given (as usual: ``:numref:`Image of Sphinx (Fig.
-   %s) <my-figure>```), the link caption will be the title of the reference.
+   %s) <my-figure>```), the link caption will serve as title of the reference.
-   As a special character, `%s` and `{number}` will be replaced to figure
+   As placeholders, `%s` and `{number}` get replaced by the figure
-   number.  `{name}` will be replaced to figure caption.
+   number and  `{name}` by the figure caption.
-   If no explicit link text is given, the value of :confval:`numfig_format` is
+   If no explicit link text is given, the :confval:`numfig_format` setting is
-   used to default value of link text.
+   used as fall-back default.
 
-   If :confval:`numfig` is ``False``, figures are not numbered.
+   If :confval:`numfig` is ``False``, figures are not numbered,
-   so this role inserts not a reference but labels or link text.
+   so this role inserts not a reference but the label or the link text.
 
 Cross-referencing other items of interest
 -----------------------------------------

sphinx/application.py

@@ -40,7 +40,7 @@ from sphinx.util import pycompat  # noqa: F401
 from sphinx.util import import_object
 from sphinx.util import logging
 from sphinx.util.tags import Tags
-from sphinx.util.osutil import ENOENT
+from sphinx.util.osutil import ENOENT, ensuredir
 from sphinx.util.console import bold  # type: ignore
 from sphinx.util.docutils import is_html5_writer_available, directive_helper
 from sphinx.util.i18n import find_catalog_source_files
@@ -159,7 +159,7 @@ class Sphinx(object):
 
         if not path.isdir(outdir):
             logger.info('making output directory...')
-            os.makedirs(outdir)
+            ensuredir(outdir)
 
         # read config
         self.tags = Tags(tags)

sphinx/builders/__init__.py

@@ -9,7 +9,6 @@
     :license: BSD, see LICENSE for details.
 """
 
-import os
 from os import path
 import warnings
 
@@ -24,7 +23,7 @@ from docutils import nodes
 from sphinx.deprecation import RemovedInSphinx20Warning
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.util import i18n, path_stabilize, logging, status_iterator
-from sphinx.util.osutil import SEP, relative_uri
+from sphinx.util.osutil import SEP, ensuredir, relative_uri
 from sphinx.util.i18n import find_catalog
 from sphinx.util.console import bold  # type: ignore
 from sphinx.util.parallel import ParallelTasks, SerialTasks, make_chunks, \
@@ -79,8 +78,7 @@ class Builder(object):
         self.confdir = app.confdir
         self.outdir = app.outdir
         self.doctreedir = app.doctreedir
-        if not path.isdir(self.doctreedir):
+        ensuredir(self.doctreedir)
-            os.makedirs(self.doctreedir)
 
         self.app = app              # type: Sphinx
         self.env = None             # type: BuildEnvironment

sphinx/cmd/quickstart.py

@@ -36,7 +36,7 @@ from six.moves.urllib.parse import quote as urlquote
 from docutils.utils import column_width
 
 from sphinx import __display_version__, package_dir
-from sphinx.util.osutil import make_filename
+from sphinx.util.osutil import ensuredir, make_filename
 from sphinx.util.console import (  # type: ignore
     purple, bold, red, turquoise, nocolor, color_terminal
 )
@@ -79,13 +79,6 @@ DEFAULTS = {
 PROMPT_PREFIX = '> '
 
 
-def mkdir_p(dir):
-    # type: (unicode) -> None
-    if path.isdir(dir):
-        return
-    os.makedirs(dir)
-
-
 # function to get input from terminal -- overridden by the test suite
 def term_input(prompt):
     # type: (unicode) -> unicode
@@ -413,11 +406,11 @@ def generate(d, overwrite=True, silent=False, templatedir=None):
         d[key + '_str'] = d[key].replace('\\', '\\\\').replace("'", "\\'")
 
     if not path.isdir(d['path']):
-        mkdir_p(d['path'])
+        ensuredir(d['path'])
 
     srcdir = d['sep'] and path.join(d['path'], 'source') or d['path']
 
-    mkdir_p(srcdir)
+    ensuredir(srcdir)
     if d['sep']:
         builddir = path.join(d['path'], 'build')
         d['exclude_patterns'] = ''
@@ -428,9 +421,9 @@ def generate(d, overwrite=True, silent=False, templatedir=None):
             'Thumbs.db', '.DS_Store',
         ])
         d['exclude_patterns'] = ', '.join(exclude_patterns)
-    mkdir_p(builddir)
+    ensuredir(builddir)
-    mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
+    ensuredir(path.join(srcdir, d['dot'] + 'templates'))
-    mkdir_p(path.join(srcdir, d['dot'] + 'static'))
+    ensuredir(path.join(srcdir, d['dot'] + 'static'))
 
     def write_file(fpath, content, newline=None):
         # type: (unicode, unicode, unicode) -> None

sphinx/ext/apidoc.py

@@ -27,7 +27,7 @@ from fnmatch import fnmatch
 from sphinx import __display_version__
 from sphinx.cmd.quickstart import EXTENSIONS
 from sphinx.util import rst
-from sphinx.util.osutil import FileAvoidWrite, walk
+from sphinx.util.osutil import FileAvoidWrite, ensuredir, walk
 
 if False:
     # For type annotation
@@ -382,8 +382,8 @@ def main(argv=sys.argv[1:]):
     if not path.isdir(rootpath):
         print('%s is not a directory.' % rootpath, file=sys.stderr)
         sys.exit(1)
-    if not path.isdir(args.destdir) and not args.dryrun:
+    if not args.dryrun:
-        os.makedirs(args.destdir)
+        ensuredir(args.destdir)
     excludes = [path.abspath(exclude) for exclude in args.exclude_pattern]
     modules = recurse_tree(rootpath, excludes, args)