1""" 2 sphinx.builders.html.transforms 3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 4 5 Transforms for HTML builder. 6 7 :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. 8 :license: BSD, see LICENSE for details. 9""" 10 11import re 12from typing import Any, Dict, List 13 14from docutils import nodes 15 16from sphinx.application import Sphinx 17from sphinx.transforms.post_transforms import SphinxPostTransform 18from sphinx.util.nodes import NodeMatcher 19 20 21class KeyboardTransform(SphinxPostTransform): 22 """Transform :kbd: role to more detailed form. 23 24 Before:: 25 26 <literal class="kbd"> 27 Control-x 28 29 After:: 30 31 <literal class="kbd compound"> 32 <literal class="kbd"> 33 Control 34 - 35 <literal class="kbd"> 36 x 37 """ 38 default_priority = 400 39 builders = ('html',) 40 pattern = re.compile(r'(?<=.)(-|\+|\^|\s+)(?=.)') 41 multiwords_keys = (('caps', 'lock'), 42 ('page' 'down'), 43 ('page', 'up'), 44 ('scroll' 'lock'), 45 ('num', 'lock'), 46 ('sys' 'rq'), 47 ('back' 'space')) 48 49 def run(self, **kwargs: Any) -> None: 50 matcher = NodeMatcher(nodes.literal, classes=["kbd"]) 51 for node in self.document.traverse(matcher): # type: nodes.literal 52 parts = self.pattern.split(node[-1].astext()) 53 if len(parts) == 1 or self.is_multiwords_key(parts): 54 continue 55 56 node['classes'].append('compound') 57 node.pop() 58 while parts: 59 if self.is_multiwords_key(parts): 60 key = ''.join(parts[:3]) 61 parts[:3] = [] 62 else: 63 key = parts.pop(0) 64 node += nodes.literal('', key, classes=["kbd"]) 65 66 try: 67 # key separator (ex. -, +, ^) 68 sep = parts.pop(0) 69 node += nodes.Text(sep) 70 except IndexError: 71 pass 72 73 def is_multiwords_key(self, parts: List[str]) -> bool: 74 if len(parts) >= 3 and parts[1].strip() == '': 75 name = parts[0].lower(), parts[2].lower() 76 if name in self.multiwords_keys: 77 return True 78 else: 79 return False 80 else: 81 return False 82 83 84def setup(app: Sphinx) -> Dict[str, Any]: 85 app.add_post_transform(KeyboardTransform) 86 87 return { 88 'version': 'builtin', 89 'parallel_read_safe': True, 90 'parallel_write_safe': True, 91 } 92