summaryrefslogtreecommitdiff
path: root/util
diff options
context:
space:
mode:
authorskullydazed <skullydazed@users.noreply.github.com>2018-03-21 23:50:38 -0700
committerJack Humbert <jack.humb@gmail.com>2018-03-22 02:50:38 -0400
commit7c9d5ace143d3cc6d767a354acde814926d566fd (patch)
tree1f2b581b6c9f6278a9e180bfcc8dd86b0a7fd2ef /util
parentf0932a8716dc946322c5ebae7f75eaa275c6220c (diff)
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
Diffstat (limited to 'util')
-rwxr-xr-xutil/generate_api_docs.sh31
-rw-r--r--util/travis_compiled_push.sh35
-rw-r--r--util/travis_docs.sh14
-rw-r--r--util/travis_push.sh17
4 files changed, 71 insertions, 26 deletions
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