Skip to content

Commit 7a09c04

Browse files
bombcheckbombcheck
committed
Merge remote-tracking branch 'sidoh/v1.10.0-wip' into dev
2 parents c23af06 + 57cb1d0 commit 7a09c04

17 files changed

Lines changed: 617 additions & 135 deletions

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
/web/node_modules
88
/web/build
99
/dist/*.bin
10+
/dist/docs
1011
.vscode/
1112
.vscode/.browse.c_cpp.db*
1213
.vscode/c_cpp_properties.json

‎.prepare_docs‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
#!/usr/bin/env bash
2+
3+
# This script sets up API documentation bundles for deployment to Github Pages.
4+
# It expects the following structure:
5+
#
6+
# In development branches:
7+
#
8+
# * ./docs/openapi.yaml - OpenAPI spec in
9+
# * ./docs/gh-pages - Any assets that should be copied to gh-pages root
10+
#
11+
# In Github Pages, it will generate:
12+
#
13+
# * ./ - Files from ./docs/gh-pages will be copied
14+
# * ./branches/<branch>/... - Deployment bundles including an index.html
15+
# and a snapshot of the Open API spec.
16+
17+
set -eo pipefail
18+
19+
prepare_docs_log() {
20+
echo "[prepare docs release] -- $@"
21+
}
22+
23+
# Only run for tagged commits
24+
if [ -z "$(git tag -l --points-at HEAD)" ]; then
25+
prepare_docs_log "Skipping non-tagged commit."
26+
exit 0
27+
fi
28+
29+
DOCS_DIR="./docs"
30+
DIST_DIR="./dist/docs"
31+
BRANCHES_DIR="${DIST_DIR}/branches"
32+
API_SPEC_FILE="${DOCS_DIR}/openapi.yaml"
33+
34+
redoc_bundle_file=$(mktemp)
35+
git_ref_version=$(git describe --always)
36+
branch_docs_dir="${BRANCHES_DIR}/${git_ref_version}"
37+
38+
# Build Redoc bundle (a single HTML file)
39+
redoc-cli bundle ${API_SPEC_FILE} -o ${redoc_bundle_file}
40+
41+
# Check out current stuff from gh-pages (we'll append to it)
42+
git fetch origin 'refs/heads/gh-pages:refs/heads/gh-pages'
43+
git checkout gh-pages -- branches || prepare_docs_log "Failed to checkout branches from gh-pages, skipping..."
44+
45+
if [ -e "./branches" ]; then
46+
mv "./branches" "${BRANCHES_DIR}"
47+
else
48+
mkdir -p "${BRANCHES_DIR}"
49+
fi
50+
51+
if [ -e "${DOCS_DIR}/gh-pages" ]; then
52+
cp -r ${DOCS_DIR}/gh-pages/* "${DIST_DIR}"
53+
else
54+
prepare_docs_log "Skipping copy of gh-pages dir, doesn't exist"
55+
fi
56+
57+
# Create the docs bundle for our ref. This will be the redoc bundle + a
58+
# snapshot of the OpenAPI spec
59+
mkdir -p "${branch_docs_dir}"
60+
cp "${API_SPEC_FILE}" "${branch_docs_dir}"
61+
cp "${redoc_bundle_file}" "${branch_docs_dir}/index.html"
62+
63+
# Update `latest` symlink to this branch
64+
rm -rf "${BRANCHES_DIR}/latest"
65+
ln -s "${branch_docs_dir}" "${BRANCHES_DIR}/latest"
66+
67+
# Create a JSON file containing a list of all branches with docs (we'll
68+
# have an index page that renders the list).
69+
ls "${BRANCHES_DIR}" | jq -Rc '.' | jq -sc '.' > "${DIST_DIR}/branches.json"

‎.travis.yml‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,20 +13,29 @@ install:
1313
- pip install -U platformio
1414
- platformio lib install
1515
- cd web && npm install && cd ..
16-
- npm install -g swagger-cli
16+
- npm install -g swagger-cli redoc-cli
1717
script:
18-
- swagger-cli validate ./openapi.yaml
18+
- swagger-cli validate ./docs/openapi.yaml
1919
- platformio run
2020
before_deploy:
2121
- ./.prepare_release
22+
- ./.prepare_docs
2223
deploy:
23-
provider: releases
24-
prerelease: true
25-
api_key:
26-
secure: p1BjM1a/u20EES+pl0+w7B/9600pvpcVYTfMiZhyMOXB0MbNm+uZKYeqiG6Tf3A9duVqMtn0R+ROO+YqL5mlnrVSi74kHMxCIF2GGtK7DIReyEI5JeF5oSi5j9bEsXu8602+1Uez8tInWgzdu2uK2G0FJF/og1Ygnk/L3haYIldIo6kL+Yd6Anlu8L2zqiovC3j3r3eO8oB6Ig6sirN+tnK0ah3dn028k+nHQIMtcc/hE7dQjglp4cGOu+NumUolhdwLdFyW7vfAafxwf9z/SL6M14pg0N8qOmT4KEg4AZQDaKn0wT7VhAvPDHjt4CgPE7QsZhEKFmW7J9LGlcWN4X3ORMkBNPnmqrkVeZEE4Vlcm3CF5kvt59ks0qwEgjpvrqxdZZxa/h9ZLEBBEXMIekA4TSAzP/e/opfry11N1lvqXQ562Jc6oEKS+xWerWSALXyZI4K1T+fkgHTZCWGH4EI3weZY/zSCAZ6a7OpgFQWU9uHlJLMkaWrp78fSPqy6zcjxhXoJnBt8BT1BMRdmZum2YX91hfJ9aRvlEmhtxKgAcPgpJ0ITwB317lKh5VqAfMNZW7pXJEYdLCmUEKXv/beTvNmRIGgu1OjZ3BWchOgh/TwX46+Lrx1zL69sfE+6cBFbC+T2QIv4dxxSQNC1K0JnRVhbD1cOpSXz+amsLS0=
27-
file_glob: true
28-
skip_cleanup: true
29-
file: dist/*.bin
30-
on:
31-
repo: sidoh/esp8266_milight_hub
32-
tags: true
24+
- provider: releases
25+
prerelease: true
26+
api_key:
27+
secure: p1BjM1a/u20EES+pl0+w7B/9600pvpcVYTfMiZhyMOXB0MbNm+uZKYeqiG6Tf3A9duVqMtn0R+ROO+YqL5mlnrVSi74kHMxCIF2GGtK7DIReyEI5JeF5oSi5j9bEsXu8602+1Uez8tInWgzdu2uK2G0FJF/og1Ygnk/L3haYIldIo6kL+Yd6Anlu8L2zqiovC3j3r3eO8oB6Ig6sirN+tnK0ah3dn028k+nHQIMtcc/hE7dQjglp4cGOu+NumUolhdwLdFyW7vfAafxwf9z/SL6M14pg0N8qOmT4KEg4AZQDaKn0wT7VhAvPDHjt4CgPE7QsZhEKFmW7J9LGlcWN4X3ORMkBNPnmqrkVeZEE4Vlcm3CF5kvt59ks0qwEgjpvrqxdZZxa/h9ZLEBBEXMIekA4TSAzP/e/opfry11N1lvqXQ562Jc6oEKS+xWerWSALXyZI4K1T+fkgHTZCWGH4EI3weZY/zSCAZ6a7OpgFQWU9uHlJLMkaWrp78fSPqy6zcjxhXoJnBt8BT1BMRdmZum2YX91hfJ9aRvlEmhtxKgAcPgpJ0ITwB317lKh5VqAfMNZW7pXJEYdLCmUEKXv/beTvNmRIGgu1OjZ3BWchOgh/TwX46+Lrx1zL69sfE+6cBFbC+T2QIv4dxxSQNC1K0JnRVhbD1cOpSXz+amsLS0=
28+
file_glob: true
29+
skip_cleanup: true
30+
file: dist/*.bin
31+
on:
32+
repo: sidoh/esp8266_milight_hub
33+
tags: true
34+
- provider: pages
35+
skip_cleanup: true
36+
local_dir: dist/docs
37+
github_token: $GITHUB_TOKEN
38+
keep_history: true
39+
on:
40+
repo: sidoh/esp8266_milight_hub
41+
tags: true

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,9 @@ The REST API is specified using
150150

151151
[openapi.yaml](openapi.yaml) contains the raw spec, created using [OpenAPI v3](https://swagger.io/docs/specification/about/).
152152

153-
[You can view generated documentation here.](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/sidoh/esp8266_milight_hub/blob/master/openapi.yaml#/)
153+
[You can view generated documentation for the master branch here.](https://sidoh.github.io/esp8266_milight_hub/master)
154+
155+
[Docs for other branches can be found here](https://sidoh.github.io/esp8266_milight_hub)
154156

155157
## MQTT
156158

‎docs/gh-pages/index.html‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<!DOCTYPE html>
2+
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
3+
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
4+
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
5+
<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]-->
6+
<head>
7+
<meta charset="utf-8">
8+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
9+
<title></title>
10+
<meta name="description" content="">
11+
<meta name="viewport" content="width=device-width">
12+
13+
<style>
14+
thead th {
15+
text-align: left;
16+
border-bottom: 1px solid #000;
17+
}
18+
th, td {
19+
padding: 0.5em 1em 0 1em;
20+
font-family: 'Courier New', Courier, monospace;
21+
}
22+
</style>
23+
24+
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.1/jquery.min.js"></script>
25+
<script>
26+
var generateDocsRow = function(x) {
27+
var html = '<tr><td>' + x + '</td>';
28+
html += '<td><a href="branches/' + x + '">Docs</a></td>';
29+
html += '<td><a href="branches/' + x + '/openapi.yaml">OpenAPI spec</a></td></tr>';
30+
31+
return html;
32+
};
33+
34+
$(function() {
35+
$.getJSON(
36+
'branches.json',
37+
function(data) {
38+
var list = $('#version-list');
39+
var html = '<thead><th>Version</th><th></th><th></th></thead><tbody>';
40+
41+
html += generateDocsRow('latest');
42+
43+
data.forEach(function(x) {
44+
if (x != 'latest') {
45+
html += generateDocsRow(x);
46+
}
47+
});
48+
49+
html += '</tbody>'
50+
51+
list.append(html);
52+
$('#loading').hide();
53+
},
54+
function(err) {
55+
console.log(err);
56+
}
57+
);
58+
});
59+
</script>
60+
</head>
61+
<body>
62+
<!--[if lt IE 7]>
63+
<p class="chromeframe">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">activate Google Chrome Frame</a> to improve your experience.</p>
64+
<![endif]-->
65+
66+
<h2>MiLight Hub REST API Documentation</h2>
67+
68+
<hr />
69+
70+
<table id="version-list"></table>
71+
<i id="loading">Loading...</i>
72+
</body>
73+
</html>

0 commit comments

Comments
 (0)