Fix #3698: Moving :doc: to std domain broke backwards compatibility

CHANGES

@@ -77,6 +77,7 @@ Bugs fixed
   1.5 series, due to hard-coded usage of ``--halt-on-error`` option. (refs #3695)
 * #3683: sphinx.websupport module is not provided by default
 * #3683: Failed to build document if builder.css_file.insert() is called
+* #3698: Moving :doc: to std domain broke backwards compatibility
 
 Testing
 --------

sphinx/transforms/post_transforms/__init__.py

@@ -9,9 +9,13 @@
     :license: BSD, see LICENSE for details.
 """
 
+import warnings
+
 from docutils import nodes
+from docutils.utils import get_source_line
 
 from sphinx import addnodes
+from sphinx.deprecation import RemovedInSphinx20Warning
 from sphinx.environment import NoUri
 from sphinx.locale import _
 from sphinx.transforms import SphinxTransform
@@ -27,6 +31,35 @@
 logger = logging.getLogger(__name__)
 
 
+class DocReferenceMigrator(SphinxTransform):
+    """Migrate :doc: reference to std domain."""
+
+    default_priority = 5  # before ReferencesResolver
+
+    def apply(self):
+        # type: () -> None
+        for node in self.document.traverse(addnodes.pending_xref):
+            if node.get('reftype') == 'doc' and node.get('refdomain') is None:
+                source, line = get_source_line(node)
+                if source and line:
+                    location = "%s:%s" % (source, line)
+                elif source:
+                    location = "%s:" % source
+                elif line:
+                    location = "<unknown>:%s" % line
+                else:
+                    location = None
+
+                message = ('Invalid pendig_xref node detected. '
+                           ':doc: reference should have refdomain=std attribute.')
+                if location:
+                    warnings.warn("%s: %s" % (location, message),
+                                  RemovedInSphinx20Warning)
+                else:
+                    warnings.warn(message, RemovedInSphinx20Warning)
+                node['refdomain'] = 'std'
+
+
 class ReferencesResolver(SphinxTransform):
     """
     Resolves cross-references on doctrees.
@@ -165,6 +198,7 @@ def apply(self):
 
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]
+    app.add_post_transform(DocReferenceMigrator)
     app.add_post_transform(ReferencesResolver)
     app.add_post_transform(OnlyNodeTransform)