273d8d6a1a
* `qmk docs`: restore `--port` and `--browser` arguments * Make docs command args always a list
62 lines
1.9 KiB
Python
62 lines
1.9 KiB
Python
"""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_args=None):
|
|
environ['PATH'] += pathsep + str(NODE_MODULES_PATH / '.bin')
|
|
|
|
args = {'capture_output': False, 'check': True}
|
|
docs_env = environ.copy()
|
|
if cli.config.general.verbose:
|
|
docs_env['DEBUG'] = 'vitepress:*,vite:*'
|
|
args['env'] = docs_env
|
|
|
|
arg_list = ['yarn', verb]
|
|
if cmd_args:
|
|
arg_list.extend(cmd_args)
|
|
|
|
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
|