diff options
author | Paul Sokolovsky <pfalcon@users.sourceforge.net> | 2016-06-12 01:13:39 +0300 |
---|---|---|
committer | Paul Sokolovsky <pfalcon@users.sourceforge.net> | 2016-06-12 01:13:39 +0300 |
commit | f6d01b8b67325ec6c5e48251f042504448b57a7a (patch) | |
tree | 673f2a43c3fff08752b6be4e7ea873fae049f9ec /docs/sphinx_selective_exclude/eager_only.py | |
parent | 9de5eb278d4bb7834c1abf15ddefdf4c85b29465 (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.py | 45 |
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) |