| # |
| # 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 |
| # |
| # SPDX-License-Identifier: Apache-2.0 |
| # |
| 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') |
| |
| 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) |
| |
| # The tags.add call above is setting tags.tags['TRUE'] = True. |
| # The operation is idempotent and will have taken effect before |
| # the next eval_condition() which may rely on it so this is thread |
| # safe both for read and writes (all other operations are local to |
| # the local nodes variable). |
| return { |
| 'parallel_read_safe': True, |
| 'parallel_write_safe': True, |
| } |