1
0
Fork 0

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
This commit is contained in:
skullydazed 2018-03-21 23:50:38 -07:00 committed by Jack Humbert
parent f0932a8716
commit 7c9d5ace14
41 changed files with 1892 additions and 97 deletions

31
util/generate_api_docs.sh Executable file
View file

@ -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

View file

@ -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

14
util/travis_docs.sh Normal file
View file

@ -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

17
util/travis_push.sh Normal file
View file

@ -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