keyboard stuff
auri.ee
1"""Handlers for the QMK documentation generator (docusaurus).
2"""
3import shutil
4from pathlib import Path
5from subprocess import DEVNULL
6from os import chdir, environ, makedirs, pathsep
7from milc import cli
8
9from qmk.constants import QMK_FIRMWARE
10
11DOCS_PATH = QMK_FIRMWARE / 'docs'
12BUILDDEFS_PATH = QMK_FIRMWARE / 'builddefs' / 'docsgen'
13BUILD_PATH = QMK_FIRMWARE / '.build'
14CACHE_PATH = BUILD_PATH / 'cache'
15NODE_MODULES_PATH = BUILD_PATH / 'node_modules'
16BUILD_DOCS_PATH = BUILD_PATH / 'docs'
17DOXYGEN_PATH = BUILD_DOCS_PATH / 'static' / 'doxygen'
18
19
20def run_docs_command(verb, cmd_args=None):
21 environ['PATH'] += pathsep + str(NODE_MODULES_PATH / '.bin')
22
23 args = {'capture_output': False, 'check': True}
24 docs_env = environ.copy()
25 if cli.config.general.verbose:
26 docs_env['DEBUG'] = 'vitepress:*,vite:*'
27 args['env'] = docs_env
28
29 arg_list = ['yarn', verb]
30 if cmd_args:
31 arg_list.extend(cmd_args)
32
33 chdir(BUILDDEFS_PATH)
34 cli.run(arg_list, **args)
35
36
37def prepare_docs_build_area(is_production):
38 if is_production:
39 # Set up a symlink for docs to be inside builddefs -- vitepress can't handle source files in parent directories
40 try:
41 docs_link = Path(BUILDDEFS_PATH / 'docs')
42 if not docs_link.exists():
43 docs_link.symlink_to(DOCS_PATH)
44 except NotImplementedError:
45 cli.log.error('Symlinks are not supported on this platform.')
46 return False
47
48 if BUILD_DOCS_PATH.exists():
49 shutil.rmtree(BUILD_DOCS_PATH)
50
51 # When not verbose we want to hide all output
52 args = {'capture_output': False if cli.config.general.verbose else True, 'check': True, 'stdin': DEVNULL}
53
54 makedirs(DOXYGEN_PATH)
55 cli.log.info('Generating doxygen docs at %s', DOXYGEN_PATH)
56 cli.run(['doxygen', 'Doxyfile'], **args)
57
58 cli.log.info('Installing vitepress dependencies')
59 run_docs_command('install')
60
61 return True