From e0260b44960cba8c013d430be41c3f0816de2fb8 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Thu, 29 Nov 2018 14:26:02 -0800 Subject: [PATCH] doc: add sphinx extension improving only directive The Sphinx .. only:: directive is limited to handling only conditional text and can't handling conditional use of directives. For example, .. only:: test .. automodule:: west.runners.core :members: is not handled. This PR monkey patches the handling of the existing .. only:: directive done by Sphinx. See https://github.com/pfalcon/sphinx_selective_exclude for details. Signed-off-by: David B. Kinder --- doc/conf.py | 3 ++- doc/extensions/eager_only.py | 45 ++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 doc/extensions/eager_only.py diff --git a/doc/conf.py b/doc/conf.py index 7aba2a6b8..e03c2e2c0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -35,7 +35,8 @@ if "RELEASE" in os.environ: # ones. sys.path.insert(0, os.path.join(os.path.abspath('.'), 'extensions')) -extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinx.ext.extlinks', 'kerneldoc'] +extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinx.ext.extlinks', + 'kerneldoc', 'eager_only'] # extlinks provides a macro template diff --git a/doc/extensions/eager_only.py b/doc/extensions/eager_only.py new file mode 100644 index 000000000..82766c2e6 --- /dev/null +++ b/doc/extensions/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)