summaryrefslogtreecommitdiff
path: root/docs/sphinx_selective_exclude/eager_only.py
diff options
context:
space:
mode:
authorPaul Sokolovsky <pfalcon@users.sourceforge.net>2016-06-12 01:13:39 +0300
committerPaul Sokolovsky <pfalcon@users.sourceforge.net>2016-06-12 01:13:39 +0300
commitf6d01b8b67325ec6c5e48251f042504448b57a7a (patch)
tree673f2a43c3fff08752b6be4e7ea873fae049f9ec /docs/sphinx_selective_exclude/eager_only.py
parent9de5eb278d4bb7834c1abf15ddefdf4c85b29465 (diff)
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.
Diffstat (limited to 'docs/sphinx_selective_exclude/eager_only.py')
-rw-r--r--docs/sphinx_selective_exclude/eager_only.py45
1 files changed, 45 insertions, 0 deletions
diff --git a/docs/sphinx_selective_exclude/eager_only.py b/docs/sphinx_selective_exclude/eager_only.py
new file mode 100644
index 000000000..82766c2e6
--- /dev/null
+++ b/docs/sphinx_selective_exclude/eager_only.py
@@ -0,0 +1,45 @@
+#
+# This is a Sphinx documentation tool extension which makes .only::
+# directives be eagerly processed early in the parsing stage. This
+# makes sure that content in .only:: blocks gets actually excluded
+# as a typical user expects, instead of bits of information in
+# these blocks leaking to documentation in various ways (e.g.,
+# indexes containing entries for functions which are actually in
+# .only:: blocks and thus excluded from documentation, etc.)
+# Note that with this extension, you may need to completely
+# rebuild a doctree when switching builders (i.e. completely
+# remove _build/doctree dir between generation of HTML vs PDF
+# documentation).
+#
+# This extension works by monkey-patching Sphinx core, so potentially
+# may not work with untested Sphinx versions. It tested to work with
+# 1.2.2 and 1.4.2
+#
+# Copyright (c) 2016 Paul Sokolovsky
+# Based on idea by Andrea Cassioli:
+# https://github.com/sphinx-doc/sphinx/issues/2150#issuecomment-171912290
+# Licensed under the terms of BSD license, see LICENSE file.
+#
+import sphinx
+from docutils.parsers.rst import directives
+
+
+class EagerOnly(sphinx.directives.other.Only):
+
+ def run(self, *args):
+ # Evaluate the condition eagerly, and if false return no nodes right away
+ env = self.state.document.settings.env
+ env.app.builder.tags.add('TRUE')
+ #print(repr(self.arguments[0]))
+ if not env.app.builder.tags.eval_condition(self.arguments[0]):
+ return []
+
+ # Otherwise, do the usual processing
+ nodes = super(EagerOnly, self).run()
+ if len(nodes) == 1:
+ nodes[0]['expr'] = 'TRUE'
+ return nodes
+
+
+def setup(app):
+ directives.register_directive('only', EagerOnly)