From 7c9d5ace143d3cc6d767a354acde814926d566fd Mon Sep 17 00:00:00 2001 From: skullydazed Date: Wed, 21 Mar 2018 23:50:38 -0700 Subject: Generate API docs from source code comments (#2491) * Generate api docs from source code * Add a bunch of doxygen comments * more doxygen comments * Add the in-progress api docs * script to generate docs from travis * Add doc generation to the travis job * make travis_docs.sh commit the work it does * make sure the docs script exits cleanly --- util/generate_api_docs.sh | 31 +++++++++++++++++++++++++++++++ util/travis_compiled_push.sh | 35 +++++++++-------------------------- util/travis_docs.sh | 14 ++++++++++++++ util/travis_push.sh | 17 +++++++++++++++++ 4 files changed, 71 insertions(+), 26 deletions(-) create mode 100755 util/generate_api_docs.sh create mode 100644 util/travis_docs.sh create mode 100644 util/travis_push.sh (limited to 'util') diff --git a/util/generate_api_docs.sh b/util/generate_api_docs.sh new file mode 100755 index 0000000000..8d7ec3101f --- /dev/null +++ b/util/generate_api_docs.sh @@ -0,0 +1,31 @@ +#!/bin/bash + +set -x + +if ! doxygen -v 2>&1 > /dev/null; then + echo "doxygen not found! Please install it!" + exit 1 +elif ! moxygen -V 2>&1 > /dev/null; then + echo -n "moxygen not found! Would you like to install it? [y/n] " + read ANSWER + case $ANSWER in + y|Y|yes|YES|Yes) + npm install -g moxygen + ;; + *) + exit 1 + ;; + esac +fi + +if [ ! -e Doxyfile ]; then + echo "Error: You must run this from the top-level qmk_firmware directory!" + exit 1 +fi + +# Generate the doxygen XML files +rm -rf doxygen +doxygen Doxyfile + +# Generate the moxygen Markdown files +moxygen -a -g -o docs/api_%s.md doxygen/xml diff --git a/util/travis_compiled_push.sh b/util/travis_compiled_push.sh index b3554b5079..6be1241220 100644 --- a/util/travis_compiled_push.sh +++ b/util/travis_compiled_push.sh @@ -1,26 +1,13 @@ #!/bin/bash -TRAVIS_BRANCH="${TRAVIS_BRANCH:master}" -TRAVIS_PULL_REQUEST="${TRAVIS_PULL_REQUEST:false}" -TRAVIS_COMMIT_MESSAGE="${TRAVIS_COMMIT_MESSAGE:-none}" -TRAVIS_COMMIT_RANGE="${TRAVIS_COMMIT_RANGE:-HEAD~1..HEAD}" - set -o errexit -o nounset +source util/travis_push.sh rev=$(git rev-parse --short HEAD) -if [[ "$TRAVIS_BRANCH" == "master" && "$TRAVIS_PULL_REQUEST" == "false" ]] ; then - -git config --global user.name "QMK Bot" -git config --global user.email "hello@qmk.fm" - -openssl aes-256-cbc -K $encrypted_b0ee987fd0fc_key -iv $encrypted_b0ee987fd0fc_iv -in secrets.tar.enc -out secrets.tar -d -tar xvf secrets.tar - -chmod 600 id_rsa_qmk_firmware -chmod 600 id_rsa_qmk.fm -eval `ssh-agent -s` -ssh-add id_rsa_qmk_firmware +if ! [[ "$TRAVIS_BRANCH" == "master" && "$TRAVIS_PULL_REQUEST" == "false" ]] ; then + exit 0 +fi # convert to unix line-endings git checkout master @@ -28,12 +15,11 @@ git diff --diff-filter=M --name-only -n 1 -z ${TRAVIS_COMMIT_RANGE} | xargs -0 d git diff --diff-filter=M --name-only -n 1 -z ${TRAVIS_COMMIT_RANGE} | xargs -0 git add git commit -m "convert to unix line-endings [skip ci]" && git push git@github.com:qmk/qmk_firmware.git master -increment_version () -{ - declare -a part=( ${1//\./ } ) - part[2]=$((part[2] + 1)) - new="${part[*]}" - echo -e "${new// /.}" +increment_version () { + declare -a part=( ${1//\./ } ) + part[2]=$((part[2] + 1)) + new="${part[*]}" + echo -e "${new// /.}" } git diff --name-only -n 1 ${TRAVIS_COMMIT_RANGE} @@ -76,7 +62,4 @@ if [[ "$TRAVIS_COMMIT_MESSAGE" != *"[skip build]"* ]] ; then git add -A git commit -m "generated from qmk/qmk_firmware@${rev}" git push git@github.com:qmk/qmk.fm.git - fi - -fi \ No newline at end of file diff --git a/util/travis_docs.sh b/util/travis_docs.sh new file mode 100644 index 0000000000..ec553952c9 --- /dev/null +++ b/util/travis_docs.sh @@ -0,0 +1,14 @@ +#!/bin/bash + +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/api_.*'; then + echo "Generating API docs..." + rm -rf doxygen + doxygen Doxyfile + moxygen -a -g -o -q docs/api_%s.md doxygen/xml + git add docs/api_* + git commit -m'autogenerated api docs for ${TRAVIS_COMMIT_RANGE}' || true + fi +fi diff --git a/util/travis_push.sh b/util/travis_push.sh new file mode 100644 index 0000000000..7eea88b148 --- /dev/null +++ b/util/travis_push.sh @@ -0,0 +1,17 @@ +# Use this by sourcing it in your script. + +TRAVIS_BRANCH="${TRAVIS_BRANCH:master}" +TRAVIS_PULL_REQUEST="${TRAVIS_PULL_REQUEST:false}" +TRAVIS_COMMIT_MESSAGE="${TRAVIS_COMMIT_MESSAGE:-none}" +TRAVIS_COMMIT_RANGE="${TRAVIS_COMMIT_RANGE:-HEAD~1..HEAD}" + +git config --global user.name "QMK Bot" +git config --global user.email "hello@qmk.fm" + +openssl aes-256-cbc -K $encrypted_b0ee987fd0fc_key -iv $encrypted_b0ee987fd0fc_iv -in secrets.tar.enc -out secrets.tar -d +tar xvf secrets.tar + +chmod 600 id_rsa_qmk_firmware +chmod 600 id_rsa_qmk.fm +eval `ssh-agent -s` +ssh-add id_rsa_qmk_firmware -- cgit v1.2.3