From 2df0bb8d03d05fe7052315438382d49014e3dcf9 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 13 Dec 2016 11:36:03 +0900 Subject: [PATCH 1/3] ``sphinx.util.compat.Directive`` class is now deprecated. --- CHANGES | 3 +++ sphinx/domains/cpp.py | 2 +- sphinx/domains/python.py | 3 +-- sphinx/domains/std.py | 3 +-- sphinx/ext/autodoc.py | 2 +- sphinx/ext/autosummary/__init__.py | 3 +-- sphinx/ext/doctest.py | 3 +-- sphinx/ext/graphviz.py | 3 +-- sphinx/ext/ifconfig.py | 2 +- sphinx/ext/inheritance_diagram.py | 3 +-- sphinx/ext/mathbase.py | 3 +-- sphinx/util/compat.py | 27 +++++++++++++++++++++++++++ 12 files changed, 40 insertions(+), 17 deletions(-) diff --git a/CHANGES b/CHANGES index 3cdd47ba5..2267a465d 100644 --- a/CHANGES +++ b/CHANGES @@ -4,6 +4,9 @@ Release 1.6 (in development) Incompatible changes -------------------- +* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead + ``docutils.parsers.rsr.Directive`` + Features added -------------- diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py index 5eeabcb11..637e75993 100644 --- a/sphinx/domains/cpp.py +++ b/sphinx/domains/cpp.py @@ -15,6 +15,7 @@ from copy import deepcopy from six import iteritems, text_type from docutils import nodes +from docutils.parsers.rst import Directive from sphinx import addnodes from sphinx.roles import XRefRole @@ -22,7 +23,6 @@ from sphinx.locale import l_, _ from sphinx.domains import Domain, ObjType from sphinx.directives import ObjectDescription from sphinx.util.nodes import make_refnode -from sphinx.util.compat import Directive from sphinx.util.pycompat import UnicodeMixin from sphinx.util.docfields import Field, GroupedField diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py index 4f0d0f1ae..377785122 100644 --- a/sphinx/domains/python.py +++ b/sphinx/domains/python.py @@ -14,7 +14,7 @@ import re from six import iteritems from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from sphinx import addnodes from sphinx.roles import XRefRole @@ -22,7 +22,6 @@ from sphinx.locale import l_, _ from sphinx.domains import Domain, ObjType, Index from sphinx.directives import ObjectDescription from sphinx.util.nodes import make_refnode -from sphinx.util.compat import Directive from sphinx.util.docfields import Field, GroupedField, TypedField if False: diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py index 53305899d..eb0ff68a4 100644 --- a/sphinx/domains/std.py +++ b/sphinx/domains/std.py @@ -15,7 +15,7 @@ import unicodedata from six import PY3, iteritems from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList from sphinx import addnodes @@ -25,7 +25,6 @@ from sphinx.domains import Domain, ObjType from sphinx.directives import ObjectDescription from sphinx.util import ws_re from sphinx.util.nodes import clean_astext, make_refnode -from sphinx.util.compat import Directive if False: # For type annotation diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index fbdd8d1ae..b09893282 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -22,6 +22,7 @@ from six import PY2, iterkeys, iteritems, itervalues, text_type, class_types, \ from docutils import nodes from docutils.utils import assemble_option_dict +from docutils.parsers.rst import Directive from docutils.statemachine import ViewList import sphinx @@ -30,7 +31,6 @@ from sphinx.locale import _ from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.application import ExtensionError from sphinx.util.nodes import nested_parse_with_titles -from sphinx.util.compat import Directive from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \ safe_getattr, object_description, is_builtin_class_method, isenumattribute from sphinx.util.docstrings import prepare_docstring diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 886623217..158692c1e 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -63,14 +63,13 @@ from types import ModuleType from six import text_type -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList from docutils import nodes import sphinx from sphinx import addnodes from sphinx.util import import_object, rst -from sphinx.util.compat import Directive from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.ext.autodoc import Options diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index 31ccb22d9..b0c1f61f5 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -21,13 +21,12 @@ import doctest from six import itervalues, StringIO, binary_type, text_type, PY2 from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives import sphinx from sphinx.builders import Builder from sphinx.util import force_decode from sphinx.util.nodes import set_source_info -from sphinx.util.compat import Directive from sphinx.util.console import bold # type: ignore from sphinx.util.osutil import fs_encoding diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index 0c29777dd..a87d7ca58 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -20,7 +20,7 @@ from hashlib import sha1 from six import text_type from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList import sphinx @@ -28,7 +28,6 @@ from sphinx.errors import SphinxError from sphinx.locale import _ from sphinx.util.i18n import search_image_for_language from sphinx.util.osutil import ensuredir, ENOENT, EPIPE, EINVAL -from sphinx.util.compat import Directive if False: # For type annotation diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py index 923e2d080..18504d94e 100644 --- a/sphinx/ext/ifconfig.py +++ b/sphinx/ext/ifconfig.py @@ -21,10 +21,10 @@ """ from docutils import nodes +from docutils.parsers.rst import Directive import sphinx from sphinx.util.nodes import set_source_info -from sphinx.util.compat import Directive if False: # For type annotation diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py index f355aa6c4..3b23c845a 100644 --- a/sphinx/ext/inheritance_diagram.py +++ b/sphinx/ext/inheritance_diagram.py @@ -48,14 +48,13 @@ from six import text_type from six.moves import builtins # type: ignore from docutils import nodes -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives import sphinx from sphinx.ext.graphviz import render_dot_html, render_dot_latex, \ render_dot_texinfo, figure_wrapper from sphinx.pycode import ModuleAnalyzer from sphinx.util import force_decode -from sphinx.util.compat import Directive if False: # For type annotation diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py index 4a5bcfb6e..4e12f62f7 100644 --- a/sphinx/ext/mathbase.py +++ b/sphinx/ext/mathbase.py @@ -10,13 +10,12 @@ """ from docutils import nodes, utils -from docutils.parsers.rst import directives +from docutils.parsers.rst import Directive, directives from sphinx.roles import XRefRole from sphinx.locale import _ from sphinx.domains import Domain from sphinx.util.nodes import make_refnode, set_source_info -from sphinx.util.compat import Directive if False: # For type annotation diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py index 0af65cbe3..73b68f5a2 100644 --- a/sphinx/util/compat.py +++ b/sphinx/util/compat.py @@ -10,12 +10,17 @@ """ from __future__ import absolute_import +import sys import warnings from docutils import nodes from docutils.parsers.rst import Directive # noqa +from docutils.parsers.rst import Directive # noqa from docutils import __version__ as _du_version + +from sphinx.deprecation import RemovedInSphinx17Warning + docutils_version = tuple(int(x) for x in _du_version.split('.')[:2]) @@ -38,3 +43,25 @@ def make_admonition(node_class, name, arguments, options, content, lineno, admonition_node['classes'] += classes state.nested_parse(content, content_offset, admonition_node) return [admonition_node] + + +class _DeprecationWrapper(object): + def __init__(self, mod, deprecated): + # type: (Any, Dict) -> None + self._mod = mod + self._deprecated = deprecated + + def __getattr__(self, attr): + if attr in self._deprecated: + warnings.warn("sphinx.util.compat.%s is deprecated and will be " + "removed in Sphinx 1.7, please use the standard " + "library version instead." % attr, + RemovedInSphinx17Warning, stacklevel=2) + return self._deprecated[attr] + return getattr(self._mod, attr) + + +sys.modules[__name__] = _DeprecationWrapper(sys.modules[__name__], dict( # type: ignore + docutils_version = docutils_version, + Directive = Directive, +)) From 50b35bb4913410f97778212e863cbc75da5820c6 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 13 Dec 2016 21:21:06 +0900 Subject: [PATCH 2/3] ``sphinx.util.compat.docutils_version`` is now deprecated --- CHANGES | 1 + sphinx/__init__.py | 4 ++-- sphinx/writers/manpage.py | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/CHANGES b/CHANGES index 2267a465d..e6d72afbe 100644 --- a/CHANGES +++ b/CHANGES @@ -6,6 +6,7 @@ Incompatible changes * ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead ``docutils.parsers.rsr.Directive`` +* ``sphinx.util.compat.docutils_version`` is now deprecated Features added -------------- diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 405fc2ff2..fb47a88ae 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -99,8 +99,8 @@ def build_main(argv=sys.argv): return 1 raise - from sphinx.util.compat import docutils_version - if docutils_version < (0, 10): + import sphinx.util.docutils + if sphinx.util.docutils.__version_info__ < (0, 10): sys.stderr.write('Error: Sphinx requires at least Docutils 0.10 to ' 'run.\n') return 1 diff --git a/sphinx/writers/manpage.py b/sphinx/writers/manpage.py index 53cf29767..249256576 100644 --- a/sphinx/writers/manpage.py +++ b/sphinx/writers/manpage.py @@ -21,7 +21,7 @@ from docutils.writers.manpage import ( from sphinx import addnodes from sphinx.deprecation import RemovedInSphinx16Warning from sphinx.locale import admonitionlabels, _ -from sphinx.util.compat import docutils_version +import sphinx.util.docutils from sphinx.util.i18n import format_date @@ -105,7 +105,7 @@ class ManualPageTranslator(BaseTranslator): self._docinfo['manual_group'] = builder.config.project # In docutils < 0.11 self.append_header() was never called - if docutils_version < (0, 11): + if sphinx.util.docutils.__version_info__ < (0, 11): self.body.append(MACRO_DEF) # Overwrite admonition label translations with our own From 3f7eefdd1acfa2dbe4e17378ddfae8f4152a6564 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 13 Dec 2016 23:38:08 +0900 Subject: [PATCH 3/3] Update CHANGES --- CHANGES | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/CHANGES b/CHANGES index e6d72afbe..f8c1a4ad0 100644 --- a/CHANGES +++ b/CHANGES @@ -4,10 +4,6 @@ Release 1.6 (in development) Incompatible changes -------------------- -* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead - ``docutils.parsers.rsr.Directive`` -* ``sphinx.util.compat.docutils_version`` is now deprecated - Features added -------------- @@ -16,6 +12,13 @@ Features added Bugs fixed ---------- +Deprecated +---------- + +* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead + ``docutils.parsers.rsr.Directive`` +* ``sphinx.util.compat.docutils_version`` is now deprecated + Release 1.5.1 (in development) ==============================