Add "orphan" metadata entry to suppress non-toctree-inclusion warnings.

doc/man/sphinx-build.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 sphinx-build manual page
 ========================
 
@@ -72,10 +74,9 @@ Options
                       <sourcedir>.
 -C                    Specifies that no conf.py file at all is to be used.
                       Configuration can only be set with the -D option.
--D <setting>=<value>  Overrides a setting from the configuration file.
+-D <setting=value>    Overrides a setting from the configuration file.
 -d <path>             Path to cached files; defaults to <outdir>/.doctrees.
--A <name>=<value>     Passes a value into the HTML templates (only for HTML
-                      builders).
+-A <name=value>       Passes a value into the HTML templates (only for HTML builders).
 -N                    Prevents colored output.
 -q                    Quiet operation, just prints warnings and errors on stderr.
 -Q                    Very quiet operation, doesn't print anything except for

doc/man/sphinx-quickstart.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 sphinx-quickstart manual page
 =============================
 
@@ -20,6 +22,7 @@ See also
 
 :manpage:`sphinx-build(1)`
 
+
 Author
 ------
 

doc/markup/misc.rst

@@ -29,6 +29,12 @@ At the moment, these metadata fields are recognized:
    If set, the web application won't display a comment form for a page generated
    from this source file.
 
+``orphan``
+   If set, warnings about this file not being included in any toctree will be
+   suppressed.
+
+   .. versionadded:: 1.0
+
 
 Meta-information markup
 -----------------------

sphinx/environment.py

@@ -1549,4 +1549,6 @@ class BuildEnvironment:
                 if docname == self.config.master_doc:
                     # the master file is not included anywhere ;)
                     continue
+                if 'orphan' in self.metadata[docname]:
+                    continue
                 self.warn(docname, 'document isn\'t included in any toctree')