diff options
| -rw-r--r-- | .github/workflows/docs.yml | 43 | ||||
| -rw-r--r-- | .travis.yml | 5 | ||||
| -rw-r--r-- | docs/cli_commands.md | 10 | ||||
| -rw-r--r-- | lib/python/qmk/cli/generate/__init__.py | 1 | ||||
| -rw-r--r-- | lib/python/qmk/cli/generate/docs.py | 37 | ||||
| -rwxr-xr-x | util/travis_docs.sh | 15 |
6 files changed, 91 insertions, 20 deletions
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000000..8855d1107f --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,43 @@ +name: Generate Docs + +on: + push: + branches: + - master + paths: + - 'tmk_core/**' + - 'quantum/**' + - 'platforms/**' + - 'docs/**' + - '.github/workflows/docs.yml' + +jobs: + generate: + runs-on: ubuntu-latest + container: qmkfm/base_container + + # protect against those who develop with their fork on master + if: github.repository == 'qmk/qmk_firmware' + + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 1 + + - name: Install dependencies + run: | + apt-get update && apt-get install -y rsync nodejs npm doxygen + npm install -g moxygen + + - name: Build docs + run: | + qmk --verbose generate-docs + + - name: Deploy + uses: JamesIves/github-pages-deploy-action@3.7.1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BASE_BRANCH: master + BRANCH: gh-pages + FOLDER: .build/docs + GIT_CONFIG_EMAIL: hello@qmk.fm diff --git a/.travis.yml b/.travis.yml index f2e8a8411d..a6533d6130 100644 --- a/.travis.yml +++ b/.travis.yml @@ -18,21 +18,16 @@ addons: - ubuntu-toolchain-r-test - llvm-toolchain-trusty-7 packages: - - pandoc - diffutils - dos2unix - - doxygen - clang-format-7 - libstdc++-7-dev -install: - - npm install -g moxygen script: - git fetch --depth=50 origin $TRAVIS_BRANCH:$TRAVIS_BRANCH - git rev-parse --short HEAD - git diff --name-only HEAD $TRAVIS_BRANCH - bash util/travis_test.sh - bash util/travis_build.sh - - bash util/travis_docs.sh after_script: bash util/travis_compiled_push.sh notifications: diff --git a/docs/cli_commands.md b/docs/cli_commands.md index b10f5d4995..69df82f953 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -286,6 +286,16 @@ This command starts a local HTTP server which you can use for browsing or improv qmk docs [-p PORT] ``` +## `qmk generate-docs` + +This command allows you to generate QMK documentation locally. It can be uses for general browsing or improving the docs. External tools such as [serve](https://www.npmjs.com/package/serve) can be used to browse the generated files. + +**Usage**: + +``` +qmk generate-docs +``` + ## `qmk kle2json` This command allows you to convert from raw KLE data to QMK Configurator JSON. It accepts either an absolute file path, or a file name in the current directory. By default it will not overwrite `info.json` if it is already present. Use the `-f` or `--force` flag to overwrite. diff --git a/lib/python/qmk/cli/generate/__init__.py b/lib/python/qmk/cli/generate/__init__.py index 4dc7607ef2..13bd1f0914 100644 --- a/lib/python/qmk/cli/generate/__init__.py +++ b/lib/python/qmk/cli/generate/__init__.py @@ -1 +1,2 @@ from . import api +from . import docs diff --git a/lib/python/qmk/cli/generate/docs.py b/lib/python/qmk/cli/generate/docs.py new file mode 100644 index 0000000000..a59a24db50 --- /dev/null +++ b/lib/python/qmk/cli/generate/docs.py @@ -0,0 +1,37 @@ +"""Build QMK documentation locally +""" +import shutil +import subprocess +from pathlib import Path + +from milc import cli + +DOCS_PATH = Path('docs/') +BUILD_PATH = Path('.build/docs/') + + +@cli.subcommand('Build QMK documentation.', hidden=False if cli.config.user.developer else True) +def generate_docs(cli): + """Invoke the docs generation process + + TODO(unclaimed): + * [ ] Add a real build step... something static docs + """ + + if BUILD_PATH.exists(): + shutil.rmtree(BUILD_PATH) + + shutil.copytree(DOCS_PATH, BUILD_PATH) + + # When not verbose we want to hide all output + args = {'check': True} + if not cli.args.verbose: + args.update({'stdout': subprocess.DEVNULL, 'stderr': subprocess.STDOUT}) + + cli.log.info('Generating internal docs...') + + # Generate internal docs + subprocess.run(['doxygen', 'Doxyfile'], **args) + subprocess.run(['moxygen', '-q', '-a', '-g', '-o', BUILD_PATH / 'internals_%s.md', 'doxygen/xml'], **args) + + cli.log.info('Successfully generated internal docs to %s.', BUILD_PATH) diff --git a/util/travis_docs.sh b/util/travis_docs.sh deleted file mode 100755 index 93c2d71867..0000000000 --- a/util/travis_docs.sh +++ /dev/null @@ -1,15 +0,0 @@ -#!/bin/bash - -source util/travis_utils.sh -source util/travis_push.sh - -if [[ "$TRAVIS_COMMIT_MESSAGE" != *"[skip docs]"* ]] ; then - if git diff --name-only ${TRAVIS_COMMIT_RANGE} | grep -e '^quantum/' -e '^tmk_core/' -e '^docs/internals_.*'; then - echo "Generating internal docs..." - rm -rf doxygen - doxygen Doxyfile - moxygen -q -a -g -o docs/internals_%s.md doxygen/xml - git add docs/internals_* - git commit -m'autogenerated internal docs for ${TRAVIS_COMMIT_RANGE}' || true - fi -fi |