Merge pull request #4821 from tk0miya/4818_warnings_on_including

Improve warning messages during including (refs: #4818)

CHANGES

@@ -71,6 +71,7 @@ Features added
 * #4834: Ensure set object descriptions are reproducible.
 * #4828: Allow to override :confval:`numfig_format` partially.  Full definition
   is not needed.
+* Improve warning messages during including (refs: #4818)
 
 Bugs fixed
 ----------

sphinx/directives/other.py

@@ -8,6 +8,7 @@
 """
 
 import re
+from contextlib import contextmanager
 
 from docutils import nodes
 from docutils.parsers.rst import directives
@@ -436,14 +437,35 @@ class Include(BaseInclude, SphinxDirective):
 
     def run(self):
         # type: () -> List[nodes.Node]
+        current_filename = self.env.doc2path(self.env.docname)
         if self.arguments[0].startswith('<') and \
            self.arguments[0].endswith('>'):
             # docutils "standard" includes, do not do path processing
             return BaseInclude.run(self)
         rel_filename, filename = self.env.relfn2path(self.arguments[0])
         self.arguments[0] = filename
         self.env.note_included(filename)
-        return BaseInclude.run(self)
+        with patched_warnings(self, current_filename):
+            return BaseInclude.run(self)
+
+
+@contextmanager
+def patched_warnings(directive, parent_filename):
+    # type: (BaseInclude, unicode) -> Generator[None, None, None]
+    """Add includee filename to the warnings during inclusion."""
+    try:
+        original = directive.state_machine.insert_input
+
+        def insert_input(input_lines, source):
+            # type: (Any, unicode) -> None
+            source += ' <included from %s>' % parent_filename
+            original(input_lines, source)
+
+        # patch insert_input() temporarily
+        directive.state_machine.insert_input = insert_input
+        yield
+    finally:
+        directive.state_machine.insert_input = original
 
 
 def setup(app):