mirror of
https://github.com/projectacrn/acrn-hypervisor.git
synced 2025-04-28 11:43:56 +00:00
a2167ae93a
Links to files in the GitHub repo's master branch should be to the files within the branch being generated. For example, in the v2.1 documentation, links should be to the v2.1 branch contents. (Previously links were being made to the master branch in all our archived content.) This creates a problem when we want to remove an obsolete file in the master branch but can't because older documentaiton incorrectly depends on it. This new extension defines a :acrn_file: and :acrn_raw: role that will create links to the given file within the current commit branch. This PR also replaces docs with hard-coded links to files in the master branch with uses of these new roles to create links to files. Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
56 lines
2.0 KiB
Python
56 lines
2.0 KiB
Python
#
|
|
# 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')
|
|
|
|
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,
|
|
}
|