Merge branch 'master' into 3570_drop_typing_from_typehints

CHANGES

@@ -1,6 +1,11 @@
 Release 1.7 (in development)
 ============================
 
+Dependencies
+------------
+
+* Add ``packaging`` package
+
 Incompatible changes
 --------------------
 
@@ -67,6 +72,8 @@ Features added
 * #4093: sphinx-build creates empty directories for unknown targets/builders
 * Add ``top-classes`` option for the ``sphinx.ext.inheritance_diagram``
   extension to limit the scope of inheritance graphs.
+* #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
 
 Features removed

doc/config.rst

@@ -293,6 +293,24 @@ General configuration
 
    .. versionadded:: 1.3
 
+.. confval:: manpages_url
+
+   A URL to cross-reference :rst:role:`manpage` directives. If this is
+   defined to ``https://manpages.debian.org/{path}``, the
+   :literal:`:manpage:`man(1)`` role will like to
+   <https://manpages.debian.org/man(1)>. The patterns available are:
+
+     * ``page`` - the manual page (``man``)
+     * ``section`` - the manual section (``1``)
+     * ``path`` - the original manual page and section specified (``man(1)``)
+
+   This also supports manpages specified as ``man.1``.
+
+   .. note:: This currently affects only HTML writers but could be
+             expanded in the future.
+
+   .. versionadded:: 1.7
+
 .. confval:: nitpicky
 
    If true, Sphinx will warn about *all* references where the target cannot be

doc/ext/doctest.rst

@@ -80,12 +80,24 @@ a comma-separated list of group names.
          .. doctest::
             :pyversion: > 3.3
 
-     The supported operands are ``<``, ``<=``, ``==``, ``>=``, ``>``, and
-     comparison is performed by `distutils.version.LooseVersion
-     <https://www.python.org/dev/peps/pep-0386/#distutils>`__.
+     The following operands are supported:
+
+     * ``~=``: Compatible release clause
+     * ``==``: Version matching clause
+     * ``!=``: Version exclusion clause
+     * ``<=``, ``>=``: Inclusive ordered comparison clause
+     * ``<``, ``>``: Exclusive ordered comparison clause
+     * ``===``: Arbitrary equality clause.
+
+     ``pyversion`` option is followed `PEP-440: Version Specifiers
+     <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`__.
 
      .. versionadded:: 1.6
 
+     .. versionchanged:: 1.7
+
+        Supported PEP-440 operands and notations
+
    Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
    signal a blank line in the expected output.  The ``<BLANKLINE>`` is removed
    when building presentation output (HTML, LaTeX etc.).

doc/markup/inline.rst

@@ -355,7 +355,8 @@ in a different style:
 .. rst:role:: manpage
 
    A reference to a Unix manual page including the section,
-   e.g. ``:manpage:`ls(1)```.
+   e.g. ``:manpage:`ls(1)```. Creates a hyperlink to an external site
+   rendering the manpage if :confval:`manpages_url` is defined.
 
 .. rst:role:: menuselection
 

setup.py

@@ -26,6 +26,7 @@ requires = [
     'imagesize',
     'requests>=2.0.0',
     'setuptools',
+    'packaging',
     'sphinxcontrib-websupport',
 ]
 

sphinx/config.py

@@ -125,6 +125,7 @@ class Config(object):
         primary_domain = ('py', 'env', [NoneType]),
         needs_sphinx = (None, None, string_classes),
         needs_extensions = ({}, None),
+        manpages_url = (None, 'env'),
         nitpicky = (False, None),
         nitpick_ignore = ([], None),
         numfig = (False, 'env'),

sphinx/ext/doctest.py

@@ -20,7 +20,8 @@ from os import path
 import doctest
 
 from six import itervalues, StringIO, binary_type, text_type, PY2
-from distutils.version import LooseVersion
+from packaging.specifiers import SpecifierSet, InvalidSpecifier
+from packaging.version import Version
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
@@ -57,28 +58,23 @@ else:
         return text
 
 
-def compare_version(ver1, ver2, operand):
-    # type: (unicode, unicode, unicode) -> bool
-    """Compare `ver1` to `ver2`, relying on `operand`.
+def is_allowed_version(spec, version):
+    # type: (unicode, unicode) -> bool
+    """Check `spec` satisfies `version` or not.
+
+    This obeys PEP-440 specifiers:
+    https://www.python.org/dev/peps/pep-0440/#version-specifiers
 
     Some examples:
 
-        >>> compare_version('3.3', '3.5', '<=')
+        >>> is_allowed_version('3.3', '<=3.5')
         True
-        >>> compare_version('3.3', '3.2', '<=')
+        >>> is_allowed_version('3.3', '<=3.2')
         False
-        >>> compare_version('3.3a0', '3.3', '<=')
+        >>> is_allowed_version('3.3', '>3.2, <4.0')
         True
     """
-    if operand not in ('<=', '<', '==', '>=', '>'):
-        raise ValueError("'%s' is not a valid operand.")
-    v1 = LooseVersion(ver1)
-    v2 = LooseVersion(ver2)
-    return ((operand == '<=' and (v1 <= v2)) or
-            (operand == '<' and (v1 < v2)) or
-            (operand == '==' and (v1 == v2)) or
-            (operand == '>=' and (v1 >= v2)) or
-            (operand == '>' and (v1 > v2)))
+    return Version(version) in SpecifierSet(spec)
 
 
 # set up the necessary directives
@@ -143,16 +139,13 @@ class TestDirective(Directive):
                 node['options'][flag] = (option[0] == '+')
         if self.name == 'doctest' and 'pyversion' in self.options:
             try:
-                option = self.options['pyversion']
-                # :pyversion: >= 3.6   -->   operand='>=', option_version='3.6'
-                operand, option_version = [item.strip() for item in option.split()]
-                running_version = platform.python_version()
-                if not compare_version(running_version, option_version, operand):
+                spec = self.options['pyversion']
+                if not is_allowed_version(spec, platform.python_version()):
                     flag = doctest.OPTIONFLAGS_BY_NAME['SKIP']
                     node['options'][flag] = True  # Skip the test
-            except ValueError:
+            except InvalidSpecifier:
                 self.state.document.reporter.warning(
-                    _("'%s' is not a valid pyversion option") % option,
+                    _("'%s' is not a valid pyversion option") % spec,
                     line=self.lineno)
         return [node]
 

sphinx/io.py

@@ -23,7 +23,7 @@ from sphinx.transforms import (
     ApplySourceWorkaround, ExtraTranslatableNodes, CitationReferences,
     DefaultSubstitutions, MoveModuleTargets, HandleCodeBlocks, SortIds,
     AutoNumbering, AutoIndexUpgrader, FilterSystemMessages,
-    UnreferencedFootnotesDetector, SphinxSmartQuotes
+    UnreferencedFootnotesDetector, SphinxSmartQuotes, ManpageLink
 )
 from sphinx.transforms.compact_bullet_list import RefOnlyBulletListTransform
 from sphinx.transforms.i18n import (
@@ -80,7 +80,7 @@ class SphinxStandaloneReader(SphinxBaseReader):
                   Locale, CitationReferences, DefaultSubstitutions, MoveModuleTargets,
                   HandleCodeBlocks, AutoNumbering, AutoIndexUpgrader, SortIds,
                   RemoveTranslatableInline, PreserveTranslatableMessages, FilterSystemMessages,
-                  RefOnlyBulletListTransform, UnreferencedFootnotesDetector
+                  RefOnlyBulletListTransform, UnreferencedFootnotesDetector, ManpageLink
                   ]  # type: List[Transform]
 
     def __init__(self, app, *args, **kwargs):
@@ -110,7 +110,7 @@ class SphinxI18nReader(SphinxBaseReader):
                   DefaultSubstitutions, MoveModuleTargets, HandleCodeBlocks,
                   AutoNumbering, SortIds, RemoveTranslatableInline,
                   FilterSystemMessages, RefOnlyBulletListTransform,
-                  UnreferencedFootnotesDetector]
+                  UnreferencedFootnotesDetector, ManpageLink]
 
     def set_lineno_for_reporter(self, lineno):
         # type: (int) -> None

sphinx/transforms/__init__.py

@@ -9,6 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
+import re
+
 from docutils import nodes
 from docutils.transforms import Transform, Transformer
 from docutils.transforms.parts import ContentsFilter
@@ -348,3 +350,21 @@ class SphinxSmartQuotes(SmartQuotes):
         for txtnode in txtnodes:
             notsmartquotable = not is_smartquotable(txtnode)
             yield (texttype[notsmartquotable], txtnode.astext())
+
+
+class ManpageLink(SphinxTransform):
+    """Find manpage section numbers and names"""
+    default_priority = 999
+
+    def apply(self):
+        for node in self.document.traverse(addnodes.manpage):
+            manpage = ' '.join([str(x) for x in node.children
+                                if isinstance(x, nodes.Text)])
+            pattern = r'^(?P<path>(?P<page>.+)[\(\.](?P<section>[1-9]\w*)?\)?)$'  # noqa
+            info = {'path': manpage,
+                    'page': manpage,
+                    'section': ''}
+            r = re.match(pattern, manpage)
+            if r:
+                info = r.groupdict()
+            node.attributes.update(info)

sphinx/writers/html.py

@@ -79,6 +79,7 @@ class HTMLTranslator(BaseTranslator):
         self.highlightopts = builder.config.highlight_options
         self.highlightlinenothreshold = sys.maxsize
         self.docnames = [builder.current_docname]  # for singlehtml builder
+        self.manpages_url = builder.config.manpages_url
         self.protect_literal_text = 0
         self.permalink_text = builder.config.html_add_permalinks
         # support backwards-compatible setting to a bool
@@ -816,9 +817,14 @@ class HTMLTranslator(BaseTranslator):
     def visit_manpage(self, node):
         # type: (nodes.Node) -> None
         self.visit_literal_emphasis(node)
+        if self.manpages_url:
+            node['refuri'] = self.manpages_url.format(**node.attributes)
+            self.visit_reference(node)
 
     def depart_manpage(self, node):
         # type: (nodes.Node) -> None
+        if self.manpages_url:
+            self.depart_reference(node)
         self.depart_literal_emphasis(node)
 
     # overwritten to add even/odd classes

sphinx/writers/html5.py

@@ -49,6 +49,7 @@ class HTML5Translator(BaseTranslator):
         self.highlightopts = builder.config.highlight_options
         self.highlightlinenothreshold = sys.maxsize
         self.docnames = [builder.current_docname]  # for singlehtml builder
+        self.manpages_url = builder.config.manpages_url
         self.protect_literal_text = 0
         self.permalink_text = builder.config.html_add_permalinks
         # support backwards-compatible setting to a bool
@@ -758,9 +759,14 @@ class HTML5Translator(BaseTranslator):
     def visit_manpage(self, node):
         # type: (nodes.Node) -> None
         self.visit_literal_emphasis(node)
+        if self.manpages_url:
+            node['refuri'] = self.manpages_url.format(**dict(node))
+            self.visit_reference(node)
 
     def depart_manpage(self, node):
         # type: (nodes.Node) -> None
+        if self.manpages_url:
+            self.depart_reference(node)
         self.depart_literal_emphasis(node)
 
     # overwritten to add even/odd classes

tests/roots/test-manpage_url/conf.py

@@ -0,0 +1,5 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+html_theme = 'classic'
+exclude_patterns = ['_build']

tests/roots/test-manpage_url/index.rst

@@ -0,0 +1,3 @@
+ * :manpage:`man(1)`
+ * :manpage:`ls.1`
+ * :manpage:`sphinx`

tests/test_build_html.py

@@ -1243,3 +1243,16 @@ def test_html_sidebar(app, status, warning):
     assert '<h3>Related Topics</h3>' not in result
     assert '<h3>This Page</h3>' not in result
     assert '<h3>Quick search</h3>' not in result
+
+
+@pytest.mark.parametrize('fname,expect', flat_dict({
+    'index.html': [(".//em/a[@href='https://example.com/man.1']", "", True),
+                   (".//em/a[@href='https://example.com/ls.1']", "", True),
+                   (".//em/a[@href='https://example.com/sphinx.']", "", True)]
+    }))
+@pytest.mark.sphinx('html', testroot='manpage_url', confoverrides={
+    'manpages_url': 'https://example.com/{page}.{section}'})
+@pytest.mark.test_params(shared_result='test_build_html_manpage_url')
+def test_html_manpage(app, cached_etree_parse, fname, expect):
+    app.build()
+    check_xpath(cached_etree_parse(app.outdir / fname), fname, *expect)

tests/test_ext_doctest.py

@@ -9,7 +9,9 @@
     :license: BSD, see LICENSE for details.
 """
 import pytest
-from sphinx.ext.doctest import compare_version
+from sphinx.ext.doctest import is_allowed_version
+from packaging.version import InvalidVersion
+from packaging.specifiers import InvalidSpecifier
 
 cleanup_called = 0
 
@@ -26,19 +28,28 @@ def test_build(app, status, warning):
     assert cleanup_called == 3, 'testcleanup did not get executed enough times'
 
 
-def test_compare_version():
-    assert compare_version('3.3', '3.4', '<') is True
-    assert compare_version('3.3', '3.2', '<') is False
-    assert compare_version('3.3', '3.4', '<=') is True
-    assert compare_version('3.3', '3.2', '<=') is False
-    assert compare_version('3.3', '3.3', '==') is True
-    assert compare_version('3.3', '3.4', '==') is False
-    assert compare_version('3.3', '3.2', '>=') is True
-    assert compare_version('3.3', '3.4', '>=') is False
-    assert compare_version('3.3', '3.2', '>') is True
-    assert compare_version('3.3', '3.4', '>') is False
-    with pytest.raises(ValueError):
-        compare_version('3.3', '3.4', '+')
+def test_is_allowed_version():
+    assert is_allowed_version('<3.4', '3.3') is True
+    assert is_allowed_version('<3.4', '3.3') is True
+    assert is_allowed_version('<3.2', '3.3') is False
+    assert is_allowed_version('<=3.4',  '3.3') is True
+    assert is_allowed_version('<=3.2',  '3.3') is False
+    assert is_allowed_version('==3.3',  '3.3') is True
+    assert is_allowed_version('==3.4',  '3.3') is False
+    assert is_allowed_version('>=3.2',  '3.3') is True
+    assert is_allowed_version('>=3.4',  '3.3') is False
+    assert is_allowed_version('>3.2', '3.3') is True
+    assert is_allowed_version('>3.4', '3.3') is False
+    assert is_allowed_version('~=3.4', '3.4.5') is True
+    assert is_allowed_version('~=3.4', '3.5.0') is True
+
+    # invalid spec
+    with pytest.raises(InvalidSpecifier):
+        is_allowed_version('&3.4', '3.5')
+
+    # invalid version
+    with pytest.raises(InvalidVersion):
+        is_allowed_version('>3.4', 'Sphinx')
 
 
 def cleanup_call():