Merge branch 'stable'

CHANGES

@@ -71,6 +71,10 @@ Features added
 Bugs fixed
 ----------
 
+* #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
+* #3829: sphinx-quickstart template is incomplete regarding use of alabaster
+* #3772: 'str object' has no attribute 'filename'
+
 Testing
 --------
 
@@ -97,7 +101,6 @@ Bugs fixed
 * #3770: Build fails when a "code-block" has the option emphasize-lines and the
   number indicated is higher than the number of lines
 * #3774: Incremental HTML building broken when using citations
-* #3772: 'str object' has no attribute 'filename'
 * #3763: got epubcheck validations error if epub_cover is set
 * #3779: 'ImportError' in sphinx.ext.autodoc due to broken 'sys.meta_path'.
   Thanks to Tatiana Tereshchenko.
@@ -319,8 +322,8 @@ Deprecated
 
 1.6b1
 
-* ``sphinx.util.compat.Directive`` class is now deprecated. Please use
+* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead
-  ``docutils.parsers.rst.Directive`` instead.
+  ``docutils.parsers.rst.Directive``
 * ``sphinx.util.compat.docutils_version`` is now deprecated
 * #2367: ``Sphinx.warn()``, ``Sphinx.info()`` and other logging methods are now
   deprecated.  Please use ``sphinx.util.logging`` (:ref:`logging-api`) instead.

CONTRIBUTING.rst

@@ -205,8 +205,8 @@ The parts of messages in Sphinx that go into builds are translated into several
 locales.  The translations are kept as gettext ``.po`` files translated from the
 master template ``sphinx/locale/sphinx.pot``.
 
-Sphinx uses `Babel <http://babel.edgewall.org>`_ to extract messages and
+Sphinx uses `Babel <http://babel.pocoo.org/en/latest/>`_ to extract messages
-maintain the catalog files.  It is integrated in ``setup.py``:
+and maintain the catalog files.  It is integrated in ``setup.py``:
 
 * Use ``python setup.py extract_messages`` to update the ``.pot`` template.
 * Use ``python setup.py update_catalog`` to update all existing language
@@ -279,7 +279,7 @@ Debugging Tips
 * JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) are
   generated by this
   `modified snowballcode generator <https://github.com/shibukawa/snowball>`_.
-  Generated `JSX <http://jsx.github.io/>`_ files are
+  Generated `JSX <https://jsx.github.io/>`_ files are
   in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_.
   You can get the resulting JavaScript files using the following command::
 

LICENSE

@@ -96,7 +96,7 @@ is available under the following license:
 SmartyPants_ license::
 
     Copyright (c) 2003 John Gruber
-    (http://daringfireball.net/)
+    (https://daringfireball.net/projects/smartypants/)
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -196,7 +196,7 @@ The included JQuery JavaScript library is available under the MIT
 license:
 
 ----------------------------------------------------------------------
-Copyright (c) 2008 John Resig, http://jquery.com/
+Copyright (c) 2008 John Resig, https://jquery.com/
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

README.rst

@@ -1,5 +1,5 @@
 .. image:: https://img.shields.io/pypi/v/sphinx.svg
-   :target: http://pypi.python.org/pypi/sphinx
+   :target: https://pypi.python.org/pypi/Sphinx
 .. image:: https://readthedocs.org/projects/sphinx/badge/
    :target: http://www.sphinx-doc.org/
    :alt: Documentation Status

babel.cfg

@@ -1,7 +1,7 @@
-# How setup this file
+# How to setup this file
-# http://babel.edgewall.org/wiki/Documentation/setup.html
+# http://babel.pocoo.org/en/latest/installation.html
 # this file description:
-# http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration
+# http://babel.pocoo.org/en/latest/messages.html
 
 # Extraction from Python source files
 [python: **.py]

doc/builders.rst

@@ -84,7 +84,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: supported_image_types
 
-   .. _Qt help: http://doc.qt.io/qt-4.8/qthelp-framework.html
+   .. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html
 
 .. module:: sphinx.builders.applehelp
 .. class:: AppleHelpBuilder
@@ -209,7 +209,7 @@ The builder's "name" must be given to the **-b** command-line option of
 Note that a direct PDF builder using ReportLab is available in `rst2pdf
 <https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or greater.  You need to add
 ``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
-``pdf``.  Refer to the `rst2pdf manual <http://ralsina.me/static/manual.pdf>`_
+``pdf``.  Refer to the `rst2pdf manual <https://ralsina.me/static/manual.pdf>`_
 for details.
 
 .. module:: sphinx.builders.text
@@ -255,7 +255,7 @@ for details.
    the terminal-based program :program:`info`.  See :ref:`texinfo-faq` for more
    details.  The Texinfo format is the official documentation system used by the
    GNU project.  More information on Texinfo can be found at
-   `<http://www.gnu.org/software/texinfo/>`_.
+   `<https://www.gnu.org/software/texinfo/>`_.
 
    .. autoattribute:: name
 

doc/develop.rst

@@ -27,19 +27,27 @@ releases on PyPI, others you can install from a checkout.
 
 This is the current list of contributed extensions in that repository:
 
-- aafig: render embedded ASCII art as nice images using aafigure_.
+- aafig: render embedded ASCII art as nice images using aafigure_
 - actdiag: embed activity diagrams by using actdiag_
 - adadomain: an extension for Ada support (Sphinx 1.0 needed)
 - ansi: parse ANSI color sequences inside documents
-- autorun: Execute code in a ``runblock`` directive.
+- argdoc: automatically generate documentation for command-line arguments, descriptions, and help text
+- astah: embed diagram by using astah
+- autoanysrc: Gather reST documentation from any source files
+- autorun: Execute code in a ``runblock`` directive
 - blockdiag: embed block diagrams by using blockdiag_
+- cacoo: embed diagram from Cacoo
+- cf3domain: a domain for CFEngine 3 policies
+- cheader: The missing c:header directive for Sphinx's built-in C domain
 - cheeseshop: easily link to PyPI packages
-- clearquest: create tables from ClearQuest_ queries.
+- clearquest: create tables from ClearQuest_ queries
 - cmakedomain_: a domain for CMake_
-- coffeedomain: a domain for (auto)documenting CoffeeScript source code.
+- coffeedomain: a domain for (auto)documenting CoffeeScript source code
-- context: a builder for ConTeXt.
+- context: a builder for ConTeXt
+- disqus: embed Disqus comments in documents
+- documentedlist: converts a Python list to a table in the generated documentation
 - doxylink: Link to external Doxygen-generated HTML documentation
-- domaintools_: A tool for easy domain creation.
+- domaintools_: A tool for easy domain creation
 - email: obfuscate email addresses
 - erlangdomain: an extension for Erlang support (Sphinx 1.0 needed)
 - exceltable: embed Excel spreadsheets into documents using exceltable_
@@ -47,47 +55,49 @@ This is the current list of contributed extensions in that repository:
   from your site content
 - findanything_: an extension to add Sublime Text 2-like findanything panels
   to your documentation to find pages, sections and index entries while typing
-- gnuplot: produces images using gnuplot_ language.
+- gnuplot: produces images using gnuplot_ language
 - googleanalytics: track web visitor statistics by using `Google Analytics`_
 - googlechart: embed charts by using `Google Chart`_
 - googlemaps: embed maps by using `Google Maps`_
-- httpdomain: a domain for documenting RESTful HTTP APIs.
+- httpdomain: a domain for documenting RESTful HTTP APIs
 - hyphenator: client-side hyphenation of HTML using hyphenator_
+- imgur: embed Imgur images, albums, and metadata in documents
 - inlinesyntaxhighlight_: inline syntax highlighting
 - lassodomain: a domain for documenting Lasso_ source code
-- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...).
+- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...)
-- lilypond: an extension inserting music scripts from Lilypond_ in PNG format.
+- lilypond: an extension inserting music scripts from Lilypond_ in PNG format
 - makedomain_: a domain for `GNU Make`_
-- matlabdomain: document MATLAB_ code.
+- matlabdomain: document MATLAB_ code
-- mockautodoc: mock imports.
+- mockautodoc: mock imports
-- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s.
+- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s
-- napoleon: supports `Google style`_ and `NumPy style`_ docstrings.
+- napoleon: supports `Google style`_ and `NumPy style`_ docstrings
 - nicovideo: embed videos from nicovideo
 - nwdiag: embed network diagrams by using nwdiag_
 - omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed)
 - osaka: convert standard Japanese doc to Osaka dialect (this is a joke extension)
-- paverutils: an alternate integration of Sphinx with Paver_.
+- paverutils: an alternate integration of Sphinx with Paver_
 - phpdomain: an extension for PHP support
 - plantuml: embed UML diagram by using PlantUML_
 - py_directive: Execute python code in a ``py`` directive and return a math
-  node.
+  node
-- rawfiles: copy raw files, like a CNAME.
+- rawfiles: copy raw files, like a CNAME
 - requirements: declare requirements wherever you need (e.g. in test
   docstrings), mark statuses and collect them in a single list
-- restbuilder: a builder for reST (reStructuredText) files.
+- restbuilder: a builder for reST (reStructuredText) files
 - rubydomain: an extension for Ruby support (Sphinx 1.0 needed)
 - sadisplay: display SqlAlchemy model sadisplay_
 - sdedit: an extension inserting sequence diagram by using Quick Sequence
   Diagram Editor (sdedit_)
 - seqdiag: embed sequence diagrams by using seqdiag_
-- slide: embed presentation slides on slideshare_ and other sites.
+- slide: embed presentation slides on slideshare_ and other sites
 - swf_: embed flash files
-- sword: an extension inserting Bible verses from Sword_.
+- sword: an extension inserting Bible verses from Sword_
-- tikz: draw pictures with the `TikZ/PGF LaTeX package`_.
+- tikz: draw pictures with the `TikZ/PGF LaTeX package`_
 - traclinks: create TracLinks_ to a Trac_ instance from within Sphinx
+- versioning: Sphinx extension that allows building versioned docs for self-hosting
 - whooshindex: whoosh indexer extension
 - youtube: embed videos from YouTube_
-- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_.
+- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_
 
 
 See the :ref:`extension tutorial <exttut>` on getting started with writing your

doc/domains.rst

@@ -34,8 +34,8 @@ documentation wants to refer to e.g. C++ and Python classes.  It also means that
 extensions that support the documentation of whole new languages are much easier
 to write.
 
-This section describes what the domains that come with Sphinx provide.  The
+This section describes what the domains that are included with Sphinx provide.
-domain API is documented as well, in the section :ref:`domain-api`.
+The domain API is documented as well, in the section :ref:`domain-api`.
 
 
 .. _basic-domain-markup:

doc/extensions.rst

@@ -4,7 +4,7 @@ Sphinx Extensions
 =================
 
 Since many projects will need special features in their documentation, Sphinx
-allows to add "extensions" to the build process, each of which can modify almost
+allows adding "extensions" to the build process, each of which can modify almost
 any aspect of document processing.
 
 This chapter describes the extensions bundled with Sphinx.  For the API

doc/faq.rst

@@ -140,7 +140,7 @@ The following list gives some hints for the creation of epub files:
   are often cut at the right margin.  The default Courier font (or variant) is
   quite wide and you can only display up to 60 characters on a line.  If you
   replace it with a narrower font, you can get more characters on a line.  You
-  may even use `FontForge <http://fontforge.github.io/>`_ and create
+  may even use `FontForge <https://fontforge.github.io/>`_ and create
   narrow variants of some free font.  In my case I get up to 70 characters on a
   line.
 
@@ -148,7 +148,7 @@ The following list gives some hints for the creation of epub files:
 
 * Test the created epubs. You can use several alternatives.  The ones I am aware
   of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
-  and Bookworm_.  For bookworm you can download the source from
+  and Bookworm_.  For Bookworm, you can download the source from
   https://code.google.com/archive/p/threepress and run your own local server.
 
 * Large floating divs are not displayed properly.
@@ -176,7 +176,7 @@ The following list gives some hints for the creation of epub files:
      $ make epub
      $ kindlegen _build/epub/yourdoc.epub
 
-  kindlegen commands doesn't accept documents that have section
+  The kindlegen command doesn't accept documents that have section
   titles surrounding ``toctree`` directive:
 
   .. code-block:: rst
@@ -191,18 +191,18 @@ The following list gives some hints for the creation of epub files:
      Section After Toc Tree
      ======================
 
-  kindlegen assumes all documents order in line, but resulting document
+  kindlegen assumes all documents order in line, but the resulting document
-  has complecated order for kindlegen::
+  has complicated order for kindlegen::
 
      ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
 
-  If you got the following error, fix document structure::
+  If you get the following error, fix your document structure::
 
      Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
      Error(prcgen):E24001: The table of content could not be built.
 
 .. _Epubcheck: https://github.com/IDPF/epubcheck
-.. _Calibre: http://calibre-ebook.com/
+.. _Calibre: https://calibre-ebook.com/
 .. _FBreader: https://fbreader.org/
 .. _Bookworm: http://www.oreilly.com/bookworm/index.html
 .. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
@@ -239,7 +239,7 @@ The exact behavior of how Emacs displays references is dependent on the variable
 both the ``*note:`` part and the ``target-id``.  This is generally the best way
 to view Sphinx-based documents since they often make frequent use of links and
 do not take this limitation into account.  However, changing this variable
-affects how all Info documents are displayed and most due take this behavior
+affects how all Info documents are displayed and most do take this behavior
 into account.
 
 If you want Emacs to display Info files produced by Sphinx using the value

doc/latex.rst

@@ -57,7 +57,7 @@ in Python string literals to reach latex.) For example::
     }
     latex_show_urls = 'footnote'
 
-.. the above was tested on Sphinx's own 1.5a2 documentation with good effect !
+.. the above was tested on Sphinx's own 1.5a2 documentation with good effect!
 
 .. highlight:: latex
 
@@ -92,8 +92,8 @@ string of ``key=value`` instructions::
 
     key1=value1,key2=value2, ...
 
-- if a key is repeated, it is its last occurence which counts,
+- if a key is repeated, it is its last occurence which is used
-- spaces around the commas and equal signs are ignored.
+- spaces around the commas and equal signs are ignored
 
 If non-empty, it will be passed as argument to the ``\sphinxsetup`` command::
 
@@ -148,7 +148,7 @@ Here are the currently available options together with their default values.
 
 .. attention::
 
-   LaTeX requires for keys with Boolean values to use **lowercase** ``true`` or
+   LaTeX requires that keys with Boolean values use **lowercase** ``true`` or
    ``false``.
 
 .. _latexsphinxsetuphmargin:
@@ -215,8 +215,8 @@ Here are the currently available options together with their default values.
 
     .. (comment) It is theoretically possible to customize this even
        more and decide at which characters a line-break can occur and whether
-       before or after, but this is accessible currently only by re-defining some
+       before or after, but this is accessible currently only by re-defining
-       macros with complicated LaTeX syntax from :file:`sphinx.sty`.
+       some macros with complicated LaTeX syntax from :file:`sphinx.sty`.
 
 ``parsedliteralwraps``
     default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
@@ -230,8 +230,7 @@ Here are the currently available options together with their default values.
     potential break-points (additionally to those allowed by LaTeX at spaces
     or for hyphenation) are currently inserted only after the characters
     ``. , ; ? ! /``. Due to TeX internals, white space in the line will be
-    stretched
+    stretched (or shrunk) in order to accomodate the linebreak.
-    (or shrinked) in order to accomodate the linebreak.
 
     .. versionadded:: 1.5
        set this option value to ``false`` to recover former behaviour.

doc/setuptools.rst

@@ -10,7 +10,7 @@ Using setuptools integration
 ----------------------------
 
 The Sphinx build can then be triggered from distutils, and some Sphinx
-options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own
+options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's own
 configuration file.
 
 For instance, from ``setup.py``::

doc/theming.rst

@@ -119,10 +119,12 @@ These themes are:
 
 * **alabaster** -- `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
   (especially as used in his Requests project), which was itself originally based on
-  @mitsuhiko's theme used for Flask & related projects. You can get options information
+  @mitsuhiko's theme used for Flask & related projects.
-  at `Alabaster theme`_ page.
+  Check out at its `installation page`_ how to set up properly
+  :confval:`html_sidebars` for its use.
 
   .. _Alabaster theme: https://pypi.python.org/pypi/alabaster
+  .. _installation page: http://alabaster.readthedocs.io/en/latest/installation.html
 
 * **classic** -- This is the classic theme, which looks like `the Python 2
   documentation <https://docs.python.org/2/>`_.  It can be customized via

sphinx/templates/quickstart/conf.py_t

@@ -96,6 +96,18 @@ todo_include_todos = {{ ext_todo }}
 #
 html_theme = 'alabaster'
 
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        # 'relations.html', # hidden by alabaster css anyway
+        'searchbox.html',
+        # 'donate.html',
+    ]
+}
+
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

sphinx/themes/basic/layout.html

@@ -106,7 +106,11 @@
     <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
     <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
     {%- for css in css_files %}
+      {%- if css|attr("rel") %}
     <link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
+      {%- else %}
+    <link href="{{ pathto(css, 1) }}" type="text/css" />
+      {%- endif %}
     {%- endfor %}
 {%- endmacro %}
 

sphinx/util/smartypants.py

@@ -143,12 +143,23 @@ def educateQuotes(text, language='en'):
 def educate_tokens(text_tokens, attr='1', language='en'):
     # type: (Iterable[Tuple[str, unicode]], unicode, unicode) -> Iterator
     """Return iterator that "educates" the items of `text_tokens`.
+
+    This is modified to intercept the ``attr='2'`` as it was used by the
+    Docutils 0.13.1 SmartQuotes transform in a hard coded way. Docutils 0.14
+    uses ``'qDe'``` and is configurable, and its choice is backported here
+    for use by Sphinx with earlier Docutils releases. Similarly ``'1'`` is
+    replaced by ``'qde'``.
+
+    Use ``attr='qDbe'``, resp. ``'qdbe'`` to recover Docutils effect of ``'2'``,
+    resp. ``'1'``.
+
+    refs: https://sourceforge.net/p/docutils/mailman/message/35869025/
     """
 
     # Parse attributes:
     # 0 : do nothing
-    # 1 : set all
+    # 1 : set all (but backticks)
-    # 2 : set all, using old school en- and em- dash shortcuts
+    # 2 : set all (but backticks), using old school en- and em- dash shortcuts
     # 3 : set all, using inverted old school en and em- dash shortcuts
     #
     # q : quotes
@@ -171,13 +182,13 @@ def educate_tokens(text_tokens, attr='1', language='en'):
         pass
     elif attr == "1":  # Do everything, turn all options on.
         do_quotes = True
-        do_backticks = 1
+        # do_backticks = 1
         do_dashes = 1
         do_ellipses = True
     elif attr == "2":
         # Do everything, turn all options on, use old school dash shorthand.
         do_quotes = True
-        do_backticks = 1
+        # do_backticks = 1
         do_dashes = 2
         do_ellipses = True
     elif attr == "3":