1#!/usr/bin/env python 2from hashlib import md5 3from pathlib import Path 4import re 5import sys 6 7import sphinx 8from sphinx.application import Sphinx 9 10# This extension uses pyyaml, report an explicit 11# error message if it's not installed 12try: 13 import yaml 14except ImportError: 15 sys.stderr.write("The Yocto Project Sphinx documentation requires PyYAML.\ 16 \nPlease make sure to install pyyaml Python package.\n") 17 sys.exit(1) 18 19__version__ = '1.0' 20 21# Variables substitutions. Uses {VAR} subst using variables defined in poky.yaml 22# Each .rst file is processed after source-read event (subst_vars_replace runs once per file) 23subst_vars = {} 24 25poky_hash = "" 26 27def subst_vars_replace(app: Sphinx, docname, source): 28 result = source[0] 29 for k in subst_vars: 30 result = result.replace("&"+k+";", subst_vars[k]) 31 source[0] = result 32 33def yocto_vars_env_get_outdated(app: Sphinx, env, added, changed, removed): 34 ''' 35 If poky.yaml changed (BUILDDIR/.poky.yaml.cache does not exist or contains 36 an md5sum different from poky.yaml's current md5sum), force rebuild of all 37 *.rst files in SOURCEDIR whose content has at least one occurence of `&.*;` 38 (see PATTERN global variable). 39 ''' 40 try: 41 poky_cache = Path(app.outdir) / ".poky.yaml.cache" 42 cache_hash = poky_cache.read_text() 43 except FileNotFoundError: 44 cache_hash = None 45 46 if poky_hash == cache_hash: 47 return [] 48 49 docs = [] 50 for p in Path(app.srcdir).rglob("*.rst"): 51 if PATTERN.search(p.read_text()): 52 p_rel_no_ext = p.relative_to(app.srcdir).parent / p.stem 53 docs.append(str(p_rel_no_ext)) 54 return docs 55 56def yocto_vars_build_finished(app: Sphinx, exception): 57 poky_cache = Path(app.outdir) / ".poky.yaml.cache" 58 poky_cache.write_text(poky_hash) 59 return [] 60 61PATTERN = re.compile(r'&(.*?);') 62def expand(val, src): 63 return PATTERN.sub(lambda m: expand(src.get(m.group(1), ''), src), val) 64 65def setup(app: Sphinx): 66 global poky_hash 67 68 with open("poky.yaml") as file: 69 hasher = md5() 70 buff = file.read() 71 hasher.update(buff.encode('utf-8')) 72 poky_hash = hasher.hexdigest() 73 subst_vars.update(yaml.safe_load(buff)) 74 75 for k in subst_vars: 76 subst_vars[k] = expand(subst_vars[k], subst_vars) 77 78 app.connect('source-read', subst_vars_replace) 79 app.connect('env-get-outdated', yocto_vars_env_get_outdated) 80 app.connect('build-finished', yocto_vars_build_finished) 81 82 return dict( 83 version = __version__, 84 parallel_read_safe = True, 85 parallel_write_safe = True 86 ) 87