diff options
Diffstat (limited to 'poky/documentation/sphinx/yocto-vars.py')
-rw-r--r-- | poky/documentation/sphinx/yocto-vars.py | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/poky/documentation/sphinx/yocto-vars.py b/poky/documentation/sphinx/yocto-vars.py new file mode 100644 index 0000000000..8795eee0a0 --- /dev/null +++ b/poky/documentation/sphinx/yocto-vars.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python +from hashlib import md5 +from pathlib import Path +import re +import sys + +import sphinx +from sphinx.application import Sphinx + +# This extension uses pyyaml, report an explicit +# error message if it's not installed +try: + import yaml +except ImportError: + sys.stderr.write("The Yocto Project Sphinx documentation requires PyYAML.\ + \nPlease make sure to install pyyaml python package.\n") + sys.exit(1) + +__version__ = '1.0' + +# Variables substitutions. Uses {VAR} subst using variables defined in poky.yaml +# Each .rst file is processed after source-read event (subst_vars_replace runs once per file) +subst_vars = {} + +poky_hash = "" + +def subst_vars_replace(app: Sphinx, docname, source): + result = source[0] + for k in subst_vars: + result = result.replace("&"+k+";", subst_vars[k]) + source[0] = result + +def yocto_vars_env_get_outdated(app: Sphinx, env, added, changed, removed): + ''' + If poky.yaml changed (BUILDDIR/.poky.yaml.cache does not exist or contains + an md5sum different from poky.yaml's current md5sum), force rebuild of all + *.rst files in SOURCEDIR whose content has at least one occurence of `&.*;` + (see PATTERN global variable). + ''' + try: + poky_cache = Path(app.outdir) / ".poky.yaml.cache" + cache_hash = poky_cache.read_text() + except FileNotFoundError: + cache_hash = None + + if poky_hash == cache_hash: + return [] + + docs = [] + for p in Path(app.srcdir).rglob("*.rst"): + if PATTERN.search(p.read_text()): + p_rel_no_ext = p.relative_to(app.srcdir).parent / p.stem + docs.append(str(p_rel_no_ext)) + return docs + +def yocto_vars_build_finished(app: Sphinx, exception): + poky_cache = Path(app.outdir) / ".poky.yaml.cache" + poky_cache.write_text(poky_hash) + return [] + +PATTERN = re.compile(r'&(.*?);') +def expand(val, src): + return PATTERN.sub(lambda m: expand(src.get(m.group(1), ''), src), val) + +def setup(app: Sphinx): + global poky_hash + + with open("poky.yaml") as file: + hasher = md5() + buff = file.read() + hasher.update(buff.encode('utf-8')) + poky_hash = hasher.hexdigest() + subst_vars.update(yaml.safe_load(buff)) + + for k in subst_vars: + subst_vars[k] = expand(subst_vars[k], subst_vars) + + app.connect('source-read', subst_vars_replace) + app.connect('env-get-outdated', yocto_vars_env_get_outdated) + app.connect('build-finished', yocto_vars_build_finished) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) |