Suppress "document isn't included in any toctree" warning if the document is included (ref: #2603)

CHANGES

@@ -8,6 +8,7 @@ Bugs fixed
 * ``width`` option of figure directive does not work if ``align`` option specified at same time (ref: #2595)
 * #2590: The ``inputenc`` package breaks compiling under lualatex and xelatex
 * #2540: date on latex front page use different font
+* Suppress "document isn't included in any toctree" warning if the document is included (ref: #2603)
 
 
 Release 1.4.2 (released May 29, 2016)

sphinx/directives/other.py

@@ -405,6 +405,7 @@ class Include(BaseInclude):
             return BaseInclude.run(self)
         rel_filename, filename = env.relfn2path(self.arguments[0])
         self.arguments[0] = filename
+        env.note_included(filename)
         return BaseInclude.run(self)
 
 

sphinx/environment.py

@@ -17,6 +17,7 @@ import types
 import bisect
 import codecs
 import string
+import fnmatch
 import unicodedata
 from os import path
 from glob import glob
@@ -175,6 +176,7 @@ class BuildEnvironment:
                                     # contains all read docnames
         self.dependencies = {}      # docname -> set of dependent file
                                     # names, relative to documentation root
+        self.included = set()       # docnames included from other documents
         self.reread_always = set()  # docnames to re-read unconditionally on
                                     # next build
 
@@ -334,6 +336,20 @@ class BuildEnvironment:
             domain.merge_domaindata(docnames, other.domaindata[domainname])
         app.emit('env-merge-info', self, docnames, other)
 
+    def path2doc(self, filename):
+        """Return the docname for the filename if the file is document.
+
+        *filename* should be absolute or relative to the source directory.
+        """
+        if filename.startswith(self.srcdir):
+            filename = filename[len(self.srcdir) + 1:]
+        for suffix in self.config.source_suffix:
+            if fnmatch.fnmatch(filename, '*' + suffix):
+                return filename[:-len(suffix)]
+        else:
+            # the file does not have docname
+            return None
+
     def doc2path(self, docname, base=True, suffix=None):
         """Return the filename for the document name.
 
@@ -832,6 +848,15 @@ class BuildEnvironment:
         """
         self.dependencies.setdefault(self.docname, set()).add(filename)
 
+    def note_included(self, filename):
+        """Add *filename* as a included from other document.
+
+        This means the document is not orphaned.
+
+        *filename* should be absolute or relative to the source directory.
+        """
+        self.included.add(self.path2doc(filename))
+
     def note_reread(self):
         """Add the current document to the list of documents that will
         automatically be re-read at the next build.
@@ -1946,6 +1971,9 @@ class BuildEnvironment:
                 if docname == self.config.master_doc:
                     # the master file is not included anywhere ;)
                     continue
+                if docname in self.included:
+                    # the document is included from other documents
+                    continue
                 if 'orphan' in self.metadata[docname]:
                     continue
                 self.warn(docname, 'document isn\'t included in any toctree')