~ruther/qmk_firmware

ref: e7a08ef1a99b407f7326e146239d785e552c9aba qmk_firmware/lib/python/qmk/docs.py -rw-r--r-- 1.9 KiB
e7a08ef1 — Joel Challis Fix broken link in PR checklist (#23877) 1 year, 4 days ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
"""Handlers for the QMK documentation generator (docusaurus).
"""
import shutil
from pathlib import Path
from subprocess import DEVNULL
from os import chdir, environ, makedirs, pathsep
from milc import cli

from qmk.constants import QMK_FIRMWARE

DOCS_PATH = QMK_FIRMWARE / 'docs'
BUILDDEFS_PATH = QMK_FIRMWARE / 'builddefs' / 'docsgen'
BUILD_PATH = QMK_FIRMWARE / '.build'
CACHE_PATH = BUILD_PATH / 'cache'
NODE_MODULES_PATH = BUILD_PATH / 'node_modules'
BUILD_DOCS_PATH = BUILD_PATH / 'docs'
DOXYGEN_PATH = BUILD_DOCS_PATH / 'static' / 'doxygen'


def run_docs_command(verb, cmd=None):
    environ['PATH'] += pathsep + str(NODE_MODULES_PATH / '.bin')

    args = {'capture_output': False if cli.config.general.verbose else True, 'check': True, 'stdin': DEVNULL}
    docs_env = environ.copy()
    if cli.config.general.verbose:
        docs_env['DEBUG'] = 'vitepress:*,vite:*'
    args['env'] = docs_env

    arg_list = ['yarn', verb]
    if cmd:
        arg_list.append(cmd)

    chdir(BUILDDEFS_PATH)
    cli.run(arg_list, **args)


def prepare_docs_build_area(is_production):
    if is_production:
        # Set up a symlink for docs to be inside builddefs -- vitepress can't handle source files in parent directories
        try:
            docs_link = Path(BUILDDEFS_PATH / 'docs')
            if not docs_link.exists():
                docs_link.symlink_to(DOCS_PATH)
        except NotImplementedError:
            cli.log.error('Symlinks are not supported on this platform.')
            return False

    if BUILD_DOCS_PATH.exists():
        shutil.rmtree(BUILD_DOCS_PATH)

    # When not verbose we want to hide all output
    args = {'capture_output': False if cli.config.general.verbose else True, 'check': True, 'stdin': DEVNULL}

    makedirs(DOXYGEN_PATH)
    cli.log.info('Generating doxygen docs at %s', DOXYGEN_PATH)
    cli.run(['doxygen', 'Doxyfile'], **args)

    cli.log.info('Installing vitepress dependencies')
    run_docs_command('install')

    return True
Do not follow this link