blob: 8795eee0a04629538178a05dc7df256eafd50ed4 [file] [log] [blame]
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001#!/usr/bin/env python
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002from hashlib import md5
3from pathlib import Path
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004import re
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05005import sys
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006
7import sphinx
8from sphinx.application import Sphinx
9
Andrew Geisslerc3d88e42020-10-02 09:45:00 -050010# 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -050019__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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050025poky_hash = ""
26
Andrew Geisslerc9f78652020-09-18 14:11:35 -050027def 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
Andrew Geissler4c19ea12020-10-27 13:52:24 -050033def 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
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061PATTERN = 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):
Andrew Geissler4c19ea12020-10-27 13:52:24 -050066 global poky_hash
67
Andrew Geisslerc9f78652020-09-18 14:11:35 -050068 with open("poky.yaml") as file:
Andrew Geissler4c19ea12020-10-27 13:52:24 -050069 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))
Andrew Geisslerc9f78652020-09-18 14:11:35 -050074
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)
Andrew Geissler4c19ea12020-10-27 13:52:24 -050079 app.connect('env-get-outdated', yocto_vars_env_get_outdated)
80 app.connect('build-finished', yocto_vars_build_finished)
Andrew Geisslerc9f78652020-09-18 14:11:35 -050081
82 return dict(
83 version = __version__,
84 parallel_read_safe = True,
85 parallel_write_safe = True
86 )