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