diff options
author | Nick Brassel <[email protected]> | 2024-05-30 12:00:41 +1000 |
---|---|---|
committer | GitHub <[email protected]> | 2024-05-30 12:00:41 +1000 |
commit | 6ef97172889ccd5db376b2a9f8825489e24fdac4 (patch) | |
tree | 334e3bf41c8554d4bee73a140822f95f60eb64e9 /lib/python | |
parent | 395766657ff98a4b1fd0dcba5917557f8acbb9e4 (diff) | |
download | qmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.tar.gz qmk_firmware-6ef97172889ccd5db376b2a9f8825489e24fdac4.zip |
Vitepress conversion of docs. (#23795)
Diffstat (limited to 'lib/python')
-rw-r--r-- | lib/python/qmk/cli/docs.py | 41 | ||||
-rw-r--r-- | lib/python/qmk/cli/generate/docs.py | 42 | ||||
-rw-r--r-- | lib/python/qmk/cli/new/keyboard.py | 2 | ||||
-rw-r--r-- | lib/python/qmk/docs.py | 61 |
4 files changed, 91 insertions, 55 deletions
diff --git a/lib/python/qmk/cli/docs.py b/lib/python/qmk/cli/docs.py index c24b914bc1..d28dddf194 100644 --- a/lib/python/qmk/cli/docs.py +++ b/lib/python/qmk/cli/docs.py @@ -1,44 +1,27 @@ """Serve QMK documentation locally """ -import http.server -import os import shutil -import webbrowser +from qmk.docs import prepare_docs_build_area, run_docs_command from milc import cli [email protected]('-p', '--port', default=8936, type=int, help='Port number to use.') [email protected]('-b', '--browser', action='store_true', help='Open the docs in the default browser.') @cli.subcommand('Run a local webserver for QMK documentation.', hidden=False if cli.config.user.developer else True) def docs(cli): """Spin up a local HTTP server for the QMK docs. """ - os.chdir('docs') - # If docsify-cli is installed, run that instead so we get live reload - if shutil.which('docsify'): - command = ['docsify', 'serve', '--port', f'{cli.config.docs.port}', '--open' if cli.config.docs.browser else ''] + if not shutil.which('doxygen'): + cli.log.error('doxygen is not installed. Please install it and try again.') + return - cli.log.info(f"Running {{fg_cyan}}{str.join(' ', command)}{{fg_reset}}") - cli.log.info("Press Control+C to exit.") + if not shutil.which('yarn'): + cli.log.error('yarn is not installed. Please install it and try again.') + return - try: - cli.run(command, capture_output=False) - except KeyboardInterrupt: - cli.log.info("Stopping HTTP server...") - else: - # Fall back to Python HTTPServer - with http.server.HTTPServer(('', cli.config.docs.port), http.server.SimpleHTTPRequestHandler) as httpd: - cli.log.info(f"Serving QMK docs at http://localhost:{cli.config.docs.port}/") - cli.log.info("Press Control+C to exit.") + if not prepare_docs_build_area(is_production=False): + return False - if cli.config.docs.browser: - webbrowser.open(f'http://localhost:{cli.config.docs.port}') - - try: - httpd.serve_forever() - except KeyboardInterrupt: - cli.log.info("Stopping HTTP server...") - finally: - httpd.shutdown() + if not cli.config.general.verbose: + cli.log.info('Serving docs at http://localhost:5173/ (Ctrl+C to stop)') + run_docs_command('run', 'docs:dev') diff --git a/lib/python/qmk/cli/generate/docs.py b/lib/python/qmk/cli/generate/docs.py index eb3099e138..5821d43b86 100644 --- a/lib/python/qmk/cli/generate/docs.py +++ b/lib/python/qmk/cli/generate/docs.py @@ -1,18 +1,12 @@ """Build QMK documentation locally """ import shutil -from pathlib import Path -from subprocess import DEVNULL +from qmk.docs import prepare_docs_build_area, run_docs_command, BUILD_DOCS_PATH from milc import cli -DOCS_PATH = Path('docs/') -BUILD_PATH = Path('.build/') -BUILD_DOCS_PATH = BUILD_PATH / 'docs' -DOXYGEN_PATH = BUILD_PATH / 'doxygen' -MOXYGEN_PATH = BUILD_DOCS_PATH / 'internals' - [email protected]('-s', '--serve', arg_only=True, action='store_true', help="Serves the generated docs once built.") @cli.subcommand('Build QMK documentation.', hidden=False if cli.config.user.developer else True) def generate_docs(cli): """Invoke the docs generation process @@ -21,24 +15,22 @@ def generate_docs(cli): * [ ] Add a real build step... something static docs """ - if BUILD_DOCS_PATH.exists(): - shutil.rmtree(BUILD_DOCS_PATH) - if DOXYGEN_PATH.exists(): - shutil.rmtree(DOXYGEN_PATH) - - shutil.copytree(DOCS_PATH, BUILD_DOCS_PATH) + if not shutil.which('doxygen'): + cli.log.error('doxygen is not installed. Please install it and try again.') + return - # When not verbose we want to hide all output - args = { - 'capture_output': False if cli.config.general.verbose else True, - 'check': True, - 'stdin': DEVNULL, - } + if not shutil.which('yarn'): + cli.log.error('yarn is not installed. Please install it and try again.') + return - cli.log.info('Generating docs...') - - # Generate internal docs - cli.run(['doxygen', 'Doxyfile'], **args) - cli.run(['moxygen', '-q', '-g', '-o', MOXYGEN_PATH / '%s.md', DOXYGEN_PATH / 'xml'], **args) + if not prepare_docs_build_area(is_production=True): + return False + cli.log.info('Building vitepress docs') + run_docs_command('run', 'docs:build') cli.log.info('Successfully generated docs to %s.', BUILD_DOCS_PATH) + + if cli.args.serve: + if not cli.config.general.verbose: + cli.log.info('Serving docs at http://localhost:4173/ (Ctrl+C to stop)') + run_docs_command('run', 'docs:preview') diff --git a/lib/python/qmk/cli/new/keyboard.py b/lib/python/qmk/cli/new/keyboard.py index 37bf2923d6..56bd05e1e3 100644 --- a/lib/python/qmk/cli/new/keyboard.py +++ b/lib/python/qmk/cli/new/keyboard.py @@ -133,7 +133,7 @@ def _question(*args, **kwargs): def prompt_keyboard(): prompt = """{fg_yellow}Name Your Keyboard Project{style_reset_all} For more infomation, see: -https://docs.qmk.fm/#/hardware_keyboard_guidelines?id=naming-your-keyboardproject +https://docs.qmk.fm/hardware_keyboard_guidelines#naming-your-keyboard-project Keyboard Name? """ diff --git a/lib/python/qmk/docs.py b/lib/python/qmk/docs.py new file mode 100644 index 0000000000..56694cf6ae --- /dev/null +++ b/lib/python/qmk/docs.py @@ -0,0 +1,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 |