From 21e231ef48869fa945133067c13aca3c96d300ad Mon Sep 17 00:00:00 2001 From: Nick Brassel Date: Mon, 1 May 2023 17:12:58 +1000 Subject: [PATCH] Move docs build to builddefs. --- {docs => builddefs/docs}/.gitignore | 0 {docs => builddefs/docs}/babel.config.js | 0 {docs => builddefs/docs}/docusaurus.config.js | 2 +- {docs => builddefs/docs}/package-lock.json | 0 {docs => builddefs/docs}/package.json | 4 +- {docs => builddefs/docs}/sidebars.js | 0 .../docs}/src/components/DocsifyForwarder.js | 0 {docs => builddefs/docs}/src/css/custom.css | 0 .../docs}/src/pages/index.module.css | 0 {docs => builddefs/docs}/static/.nojekyll | 0 {docs => builddefs/docs}/static/CNAME | 0 .../docs}/static/img/favicon.ico | Bin .../docs}/static/img/favicon.png | Bin .../docs}/static/img/qmk-new-dark.svg | 0 .../docs}/static/img/qmk-new-light.svg | 0 .../docs}/static/img/qmk-social-card.jpg | Bin lib/python/qmk/cli/docs.py | 37 ++------------- lib/python/qmk/cli/generate/docs.py | 43 ++++-------------- 18 files changed, 14 insertions(+), 72 deletions(-) rename {docs => builddefs/docs}/.gitignore (100%) rename {docs => builddefs/docs}/babel.config.js (100%) rename {docs => builddefs/docs}/docusaurus.config.js (99%) rename {docs => builddefs/docs}/package-lock.json (100%) rename {docs => builddefs/docs}/package.json (89%) rename {docs => builddefs/docs}/sidebars.js (100%) rename {docs => builddefs/docs}/src/components/DocsifyForwarder.js (100%) rename {docs => builddefs/docs}/src/css/custom.css (100%) rename {docs => builddefs/docs}/src/pages/index.module.css (100%) rename {docs => builddefs/docs}/static/.nojekyll (100%) rename {docs => builddefs/docs}/static/CNAME (100%) rename {docs => builddefs/docs}/static/img/favicon.ico (100%) rename {docs => builddefs/docs}/static/img/favicon.png (100%) rename {docs => builddefs/docs}/static/img/qmk-new-dark.svg (100%) rename {docs => builddefs/docs}/static/img/qmk-new-light.svg (100%) rename {docs => builddefs/docs}/static/img/qmk-social-card.jpg (100%) diff --git a/docs/.gitignore b/builddefs/docs/.gitignore similarity index 100% rename from docs/.gitignore rename to builddefs/docs/.gitignore diff --git a/docs/babel.config.js b/builddefs/docs/babel.config.js similarity index 100% rename from docs/babel.config.js rename to builddefs/docs/babel.config.js diff --git a/docs/docusaurus.config.js b/builddefs/docs/docusaurus.config.js similarity index 99% rename from docs/docusaurus.config.js rename to builddefs/docs/docusaurus.config.js index 9674ed8f57e..74f84230e02 100644 --- a/docs/docusaurus.config.js +++ b/builddefs/docs/docusaurus.config.js @@ -42,7 +42,7 @@ const config = { "@docusaurus/plugin-content-docs", { sidebarPath: require.resolve("./sidebars.js"), - path: ".", + path: "../../docs", routeBasePath: "/", exclude: [ "node_modules", diff --git a/docs/package-lock.json b/builddefs/docs/package-lock.json similarity index 100% rename from docs/package-lock.json rename to builddefs/docs/package-lock.json diff --git a/docs/package.json b/builddefs/docs/package.json similarity index 89% rename from docs/package.json rename to builddefs/docs/package.json index 3e9663bb53d..1a057f45b31 100644 --- a/docs/package.json +++ b/builddefs/docs/package.json @@ -4,12 +4,12 @@ "private": true, "scripts": { "docusaurus": "docusaurus", - "start": "docusaurus start", + "start": "docusaurus start --host 0.0.0.0 --port 8936", "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", - "serve": "docusaurus serve", + "serve": "docusaurus serve --host 0.0.0.0 --port 8936", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids" }, diff --git a/docs/sidebars.js b/builddefs/docs/sidebars.js similarity index 100% rename from docs/sidebars.js rename to builddefs/docs/sidebars.js diff --git a/docs/src/components/DocsifyForwarder.js b/builddefs/docs/src/components/DocsifyForwarder.js similarity index 100% rename from docs/src/components/DocsifyForwarder.js rename to builddefs/docs/src/components/DocsifyForwarder.js diff --git a/docs/src/css/custom.css b/builddefs/docs/src/css/custom.css similarity index 100% rename from docs/src/css/custom.css rename to builddefs/docs/src/css/custom.css diff --git a/docs/src/pages/index.module.css b/builddefs/docs/src/pages/index.module.css similarity index 100% rename from docs/src/pages/index.module.css rename to builddefs/docs/src/pages/index.module.css diff --git a/docs/static/.nojekyll b/builddefs/docs/static/.nojekyll similarity index 100% rename from docs/static/.nojekyll rename to builddefs/docs/static/.nojekyll diff --git a/docs/static/CNAME b/builddefs/docs/static/CNAME similarity index 100% rename from docs/static/CNAME rename to builddefs/docs/static/CNAME diff --git a/docs/static/img/favicon.ico b/builddefs/docs/static/img/favicon.ico similarity index 100% rename from docs/static/img/favicon.ico rename to builddefs/docs/static/img/favicon.ico diff --git a/docs/static/img/favicon.png b/builddefs/docs/static/img/favicon.png similarity index 100% rename from docs/static/img/favicon.png rename to builddefs/docs/static/img/favicon.png diff --git a/docs/static/img/qmk-new-dark.svg b/builddefs/docs/static/img/qmk-new-dark.svg similarity index 100% rename from docs/static/img/qmk-new-dark.svg rename to builddefs/docs/static/img/qmk-new-dark.svg diff --git a/docs/static/img/qmk-new-light.svg b/builddefs/docs/static/img/qmk-new-light.svg similarity index 100% rename from docs/static/img/qmk-new-light.svg rename to builddefs/docs/static/img/qmk-new-light.svg diff --git a/docs/static/img/qmk-social-card.jpg b/builddefs/docs/static/img/qmk-social-card.jpg similarity index 100% rename from docs/static/img/qmk-social-card.jpg rename to builddefs/docs/static/img/qmk-social-card.jpg diff --git a/lib/python/qmk/cli/docs.py b/lib/python/qmk/cli/docs.py index c24b914bc13..13c7ea38a93 100644 --- a/lib/python/qmk/cli/docs.py +++ b/lib/python/qmk/cli/docs.py @@ -1,44 +1,13 @@ """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 -@cli.argument('-p', '--port', default=8936, type=int, help='Port number to use.') -@cli.argument('-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 ''] - - cli.log.info(f"Running {{fg_cyan}}{str.join(' ', command)}{{fg_reset}}") - cli.log.info("Press Control+C to exit.") - - 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 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() + prepare_docs_build_area() + run_docs_command('start', False) diff --git a/lib/python/qmk/cli/generate/docs.py b/lib/python/qmk/cli/generate/docs.py index f834b7f5560..5079578827c 100644 --- a/lib/python/qmk/cli/generate/docs.py +++ b/lib/python/qmk/cli/generate/docs.py @@ -1,18 +1,10 @@ """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_DOCS_PATH / 'static' / 'doxygen' -# MOXYGEN_PATH = BUILD_DOCS_PATH / 'internals' - - +@cli.argument('-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,30 +13,11 @@ 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) - - cli.log.info('Copying %s folder to %s', DOCS_PATH, BUILD_DOCS_PATH) - # ignore .gitignore'd folders when we're testing locally - shutil.copytree(DOCS_PATH, BUILD_DOCS_PATH, ignore=shutil.ignore_patterns("node_modules", "build", ".docusaurus")) - - # When not verbose we want to hide all output - args = { - 'capture_output': False if cli.config.general.verbose else True, - 'check': True, - 'stdin': DEVNULL, - } - - cli.log.info('Generating doxygen docs at %s', DOXYGEN_PATH) - cli.run(['doxygen', 'Doxyfile'], **args) - # cli.run(['moxygen', '-q', '-g', '-o', MOXYGEN_PATH / '%s.md', DOXYGEN_PATH / 'xml'], **args) - - cli.log.info('Installing docusaurus dependencies') - cli.run(['npm', 'ci', '--prefix', BUILD_DOCS_PATH], **args) - - cli.log.info('Building docusarus docs') - cli.run(['npm', 'run', '--prefix', BUILD_DOCS_PATH, 'build'], **args) + prepare_docs_build_area() + cli.log.info('Building docusaurus docs') + run_docs_command('build') cli.log.info('Successfully generated docs to %s.', BUILD_DOCS_PATH) + + if cli.args.serve: + run_docs_command('serve', False)