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:
parent
f0932a8716
commit
7c9d5ace14
41 changed files with 1892 additions and 97 deletions
31
util/generate_api_docs.sh
Executable file
31
util/generate_api_docs.sh
Executable 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
|
|
@ -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
14
util/travis_docs.sh
Normal 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
17
util/travis_push.sh
Normal 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
|
Loading…
Add table
Add a link
Reference in a new issue