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

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 000000000..8d7ec3101
--- /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 b3554b507..6be124122 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 000000000..ec553952c
--- /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 000000000..7eea88b14
--- /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