qmk_firmware

QMK firmware for my keyboards (Corne, Sweep Ferris) and trackball (Ploopy Adept)
Log | Files | Refs | Submodules | LICENSE

docs.py (1943B)

      1 """Handlers for the QMK documentation generator (docusaurus).
      2 """
      3 import shutil
      4 from pathlib import Path
      5 from subprocess import DEVNULL
      6 from os import chdir, environ, makedirs, pathsep
      7 from milc import cli
      8 
      9 from qmk.constants import QMK_FIRMWARE
     10 
     11 DOCS_PATH = QMK_FIRMWARE / 'docs'
     12 BUILDDEFS_PATH = QMK_FIRMWARE / 'builddefs' / 'docsgen'
     13 BUILD_PATH = QMK_FIRMWARE / '.build'
     14 CACHE_PATH = BUILD_PATH / 'cache'
     15 NODE_MODULES_PATH = BUILD_PATH / 'node_modules'
     16 BUILD_DOCS_PATH = BUILD_PATH / 'docs'
     17 DOXYGEN_PATH = BUILD_DOCS_PATH / 'static' / 'doxygen'
     18 
     19 
     20 def 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 
     37 def 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