docs: Add sphinx_selective_exclude extension suite.

Designed specifically to workaround issues we were facing with generating
multiple conditionalized output docsets from a single master doctree.
Extensions were factored out into a separate project, based on the fact
that many other Sphinx users experience similar or related problems:
https://github.com/pfalcon/sphinx_selective_exclude

Corresponds to the 182f4a8da57 upstream revision.

1 files changed, 34 insertions, 0 deletions

diff --git a/docs/sphinx_selective_exclude/search_auto_exclude.py b/docs/sphinx_selective_exclude/search_auto_exclude.py
new file mode 100644
index 0000000000..b8b326dd2c
--- /dev/null
+++ b/docs/sphinx_selective_exclude/search_auto_exclude.py
@@ -0,0 +1,34 @@
+#
+# This is a Sphinx documentation tool extension which allows to
+# automatically exclude from full-text search index document
+# which are not referenced via toctree::. It's intended to be
+# used with toctrees conditional on only:: directive, with the
+# idea being that if you didn't include it in the ToC, you don't
+# want the docs being findable by search either (for example,
+# because these docs contain information not pertinent to a
+# particular product configuration).
+#
+# This extension depends on "eager_only" extension and won't work
+# without it.
+#
+# Copyright (c) 2016 Paul Sokolovsky
+# Licensed under the terms of BSD license, see LICENSE file.
+#
+import sphinx
+
+
+org_StandaloneHTMLBuilder_index_page = None
+
+
+def StandaloneHTMLBuilder_index_page(self, pagename, doctree, title):
+    if pagename not in self.env.files_to_rebuild:
+        if pagename != self.env.config.master_doc and 'orphan' not in self.env.metadata[pagename]:
+            print("Excluding %s from full-text index because it's not referenced in ToC" % pagename)
+            return
+    return org_StandaloneHTMLBuilder_index_page(self, pagename, doctree, title)
+
+
+def setup(app):
+    global org_StandaloneHTMLBuilder_index_page
+    org_StandaloneHTMLBuilder_index_page = sphinx.builders.html.StandaloneHTMLBuilder.index_page
+    sphinx.builders.html.StandaloneHTMLBuilder.index_page = StandaloneHTMLBuilder_index_page