Skip to content

Commit

Permalink
Add JSON Documentation & Document Generator (#180)
Browse files Browse the repository at this point in the history
  • Loading branch information
noursaidi authored Sep 9, 2021
1 parent 1834f3d commit d3b129e
Show file tree
Hide file tree
Showing 49 changed files with 528 additions and 50 deletions.
8 changes: 8 additions & 0 deletions .github/workflows/testing.yml
Original file line number Diff line number Diff line change
Expand Up @@ -71,3 +71,11 @@ jobs:
run: |
echo Pubber output logs:
cat pubber.out || true
docs:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v2
- name: schema docs
run: bin/gendocs check
53 changes: 53 additions & 0 deletions bin/gendocs
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#!/bin/bash -e

ROOT_DIR=$(realpath $(dirname $0)/..)
cd $ROOT_DIR

OUTPUT_DIR=$ROOT_DIR/gencode/docs
TMP_DIR=$ROOT_DIR/tmp/schema

schema_files=`ls schema/*.json`

if [ "$1" == check ]; then
mkdir -p $TMP_DIR
sha1sum $schema_files > $TMP_DIR/schema.hash
diff $TMP_DIR/schema.hash $OUTPUT_DIR/schema.hash
echo Schema hashes in $OUTPUT_DIR/schema.hash are up-to-date.
git diff --exit-code $OUTPUT_DIR/schema.hash
exit 0
fi

rm -rf $OUTPUT_DIR
mkdir -p $OUTPUT_DIR

sha1sum $schema_files > $OUTPUT_DIR/schema.hash

# Make a copy of the schema files into a tmp folder for any pre generator fixes
rm -rf $TMP_DIR
mkdir -p $TMP_DIR
cp -r schema/. $TMP_DIR

# Remove file: prefix from references so document generator works
find $TMP_DIR -type f -exec sed -i '' 's/file://' {} \;

schemas="state event_system event_pointset event_discovery config metadata envelope"

for schema in $schemas; do
python3 bin/gendocs.py $schema $TMP_DIR $OUTPUT_DIR
done

rm -rf $TMP_DIR

# Convert github doc links to relative links for hosted/downloaded docs
#RELATIVE_LINK="..\/"
#find $OUTPUT_DIR -type f -exec sed -i '' "s/$ABSOLUTE_LINK/$RELATIVE_LINK/" {} \;
#ABSOLUTE_LINK="https:\/\/github.com\/faucetsdn\/udmi\/blob\/master\/docs\/"

# Create index page with links to different schemas
cp etc/schema_index_template.html $OUTPUT_DIR/index.html

for schema in $schemas; do
sed -i '' "s/<!--SCHEMALINK-->/\
<div class=\"card\"><a href=\"$schema.html\">$schema<\/a><\/div><!--SCHEMALINK-->/"\
$OUTPUT_DIR/index.html
done
18 changes: 18 additions & 0 deletions bin/gendocs.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
import sys

from json_schema_for_humans.generate import generate_from_filename
from json_schema_for_humans.generation_configuration import GenerationConfiguration

config = GenerationConfiguration(copy_css=True,
expand_buttons=True,
minify=False,
link_to_reused_ref=False)

schema = sys.argv[1]
source_dir = sys.argv[2]
output_dir = sys.argv[3]

schema_path = source_dir + "/" + schema + ".json"
output_path = output_dir + "/" + schema + ".html"

generate_from_filename(schema_path, output_path, config=config)
1 change: 1 addition & 0 deletions etc/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
json-schema-for-humans
26 changes: 26 additions & 0 deletions etc/schema_index_template.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<html lang="en" class="fa-events-icons-ready">
<head>
<link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Overpass:300,400,600,800">
<link href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
<link rel="stylesheet" type="text/css" href="schema_doc.css">
<script src="https://use.fontawesome.com/facf9fa52c.js"></script>
<link href="https://use.fontawesome.com/facf9fa52c.css" media="all" rel="stylesheet">
<script src="schema_doc.min.js"></script>
<meta charset="utf-8">
<style type="text/css">
.card a{
padding: 30px;
background-color: rgba(0,0,0,.03);
font-size: 18px;
font-weight: 400;
}
</style>
<title>UDMI Schema</title>
</head>
<body>
<h1>UDMI Schema</h1>
<br>
<!--SCHEMALINK-->
</body>
</html>
6 changes: 6 additions & 0 deletions gencode/docs/config.html

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions gencode/docs/envelope.html
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
<!DOCTYPE html><html lang=en> <head><link rel=stylesheet type=text/css href="https://fonts.googleapis.com/css?family=Overpass:300,400,600,800"><script src=https://code.jquery.com/jquery-3.4.1.min.js integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin=anonymous></script><link href=https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css rel=stylesheet integrity=sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T crossorigin=anonymous><script src=https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js integrity=sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM crossorigin=anonymous></script><link rel=stylesheet type=text/css href=schema_doc.css><script src=https://use.fontawesome.com/facf9fa52c.js></script><script src=schema_doc.min.js></script><meta charset=utf-8><title>Envelope</title></head> <body onload=anchorOnLoad(); id=root><h1>Envelope</h1><div class=text-right> <button class="btn btn-primary" type=button data-toggle=collapse data-target=.collapse:not(.show) aria-expanded=false>Expand all</button> <button class="btn btn-primary" type=button data-toggle=collapse data-target=.collapse.show aria-expanded=false>Collapse all</button> </div> <div class=breadcrumbs></div><span class="badge badge-dark value-type">Type: object</span><br> <span class=description><p>The UDMI <code>envelope</code> is not a message itself, per se, but the attributes and other information that is delivered along with a message. Read more: <a href=https://github.com/faucetsdn/udmi/blob/master/docs/envelope.md>https://github.com/faucetsdn/udmi/blob/master/docs/envelope.md</a></p> </span> <div class=accordion id=accordiondeviceId> <div class=card> <div class=card-header id=headingdeviceId> <h2 class=mb-0> <button class="btn btn-link property-name-button" type=button data-toggle=collapse data-target=#deviceId aria-expanded aria-controls=deviceId onclick="setAnchor('#deviceId')"><span class=property-name>deviceId</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div id=deviceId class="collapse property-definition-div" aria-labelledby=headingdeviceId data-parent=#accordiondeviceId> <div class="card-body pl-5"> <div class=breadcrumbs>root <svg width=1em height=1em viewbox="0 0 16 16" class="bi bi-arrow-right-short" fill=currentColor xmlns=http://www.w3.org/2000/svg> <path fill-rule=evenodd d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"/> </svg> <a href=#deviceId onclick="anchorLink('deviceId')">deviceId</a></div><span class="badge badge-dark value-type">Type: string</span><br> <span class=pattern-value id=deviceId_pattern>Must match regular expression: <code>^[A-Z]{2,6}-[0-9]{1,6}$</code></span> </div> </div> </div> </div> <div class=accordion id=accordiondeviceNumId> <div class=card> <div class=card-header id=headingdeviceNumId> <h2 class=mb-0> <button class="btn btn-link property-name-button" type=button data-toggle=collapse data-target=#deviceNumId aria-expanded aria-controls=deviceNumId onclick="setAnchor('#deviceNumId')"><span class=property-name>deviceNumId</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div id=deviceNumId class="collapse property-definition-div" aria-labelledby=headingdeviceNumId data-parent=#accordiondeviceNumId> <div class="card-body pl-5"> <div class=breadcrumbs>root <svg width=1em height=1em viewbox="0 0 16 16" class="bi bi-arrow-right-short" fill=currentColor xmlns=http://www.w3.org/2000/svg> <path fill-rule=evenodd d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"/> </svg> <a href=#deviceNumId onclick="anchorLink('deviceNumId')">deviceNumId</a></div><span class="badge badge-dark value-type">Type: string</span><br> <span class=pattern-value id=deviceNumId_pattern>Must match regular expression: <code>^[0-9]+$</code></span> </div> </div> </div> </div> <div class=accordion id=accordiondeviceRegistryId> <div class=card> <div class=card-header id=headingdeviceRegistryId> <h2 class=mb-0> <button class="btn btn-link property-name-button" type=button data-toggle=collapse data-target=#deviceRegistryId aria-expanded aria-controls=deviceRegistryId onclick="setAnchor('#deviceRegistryId')"><span class=property-name>deviceRegistryId</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div id=deviceRegistryId class="collapse property-definition-div" aria-labelledby=headingdeviceRegistryId data-parent=#accordiondeviceRegistryId> <div class="card-body pl-5"> <div class=breadcrumbs>root <svg width=1em height=1em viewbox="0 0 16 16" class="bi bi-arrow-right-short" fill=currentColor xmlns=http://www.w3.org/2000/svg> <path fill-rule=evenodd d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"/> </svg> <a href=#deviceRegistryId onclick="anchorLink('deviceRegistryId')">deviceRegistryId</a></div><span class="badge badge-dark value-type">Type: string</span><br> <span class=pattern-value id=deviceRegistryId_pattern>Must match regular expression: <code>^[a-zA-Z][-a-zA-Z0-9._+~%]*[a-zA-Z0-9]$</code></span> </div> </div> </div> </div> <div class=accordion id=accordionprojectId> <div class=card> <div class=card-header id=headingprojectId> <h2 class=mb-0> <button class="btn btn-link property-name-button" type=button data-toggle=collapse data-target=#projectId aria-expanded aria-controls=projectId onclick="setAnchor('#projectId')"><span class=property-name>projectId</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div id=projectId class="collapse property-definition-div" aria-labelledby=headingprojectId data-parent=#accordionprojectId> <div class="card-body pl-5"> <div class=breadcrumbs>root <svg width=1em height=1em viewbox="0 0 16 16" class="bi bi-arrow-right-short" fill=currentColor xmlns=http://www.w3.org/2000/svg> <path fill-rule=evenodd d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"/> </svg> <a href=#projectId onclick="anchorLink('projectId')">projectId</a></div><span class="badge badge-dark value-type">Type: string</span><br> <span class=pattern-value id=projectId_pattern>Must match regular expression: <code>^([.a-z]+:)?[a-z][-a-z0-9]*[a-z0-9]$</code></span> </div> </div> </div> </div> <div class=accordion id=accordionsubFolder> <div class=card> <div class=card-header id=headingsubFolder> <h2 class=mb-0> <button class="btn btn-link property-name-button" type=button data-toggle=collapse data-target=#subFolder aria-expanded aria-controls=subFolder onclick="setAnchor('#subFolder')"><span class=property-name>subFolder</span> <span class="badge badge-warning required-property">Required</span></button> </h2> </div> <div id=subFolder class="collapse property-definition-div" aria-labelledby=headingsubFolder data-parent=#accordionsubFolder> <div class="card-body pl-5"> <div class=breadcrumbs>root <svg width=1em height=1em viewbox="0 0 16 16" class="bi bi-arrow-right-short" fill=currentColor xmlns=http://www.w3.org/2000/svg> <path fill-rule=evenodd d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"/> </svg> <a href=#subFolder onclick="anchorLink('subFolder')">subFolder</a></div><span class="badge badge-dark value-type">Type: enum (of string)</span><br> <div class=enum-value id=subFolder_enum> <h4>Must be one of:</h4> <ul class=list-group><li class="list-group-item enum-item">"config"</li><li class="list-group-item enum-item">"discovery"</li><li class="list-group-item enum-item">"system"</li><li class="list-group-item enum-item">"metadata"</li><li class="list-group-item enum-item">"pointset"</li><li class="list-group-item enum-item">"state"</li></ul> </div> </div> </div> </div> </div> <div class=accordion id=accordionadditionalProperties> <div class=card> <div class=card-header id=headingadditionalProperties> <h2 class=mb-0> <button class="btn btn-link property-name-button" type=button data-toggle=collapse data-target=#additionalProperties aria-expanded aria-controls=additionalProperties onclick="setAnchor('#additionalProperties')"><em><span class=property-name>Additional Properties</span></em></button> </h2> </div> <div id=additionalProperties class="collapse property-definition-div" aria-labelledby=headingadditionalProperties data-parent=#accordionadditionalProperties> <div class="card-body pl-5"><p class=additional-properties>Additional Properties of any type are allowed.</p> <div class=breadcrumbs>root <svg width=1em height=1em viewbox="0 0 16 16" class="bi bi-arrow-right-short" fill=currentColor xmlns=http://www.w3.org/2000/svg> <path fill-rule=evenodd d="M4 8a.5.5 0 0 1 .5-.5h5.793L8.146 5.354a.5.5 0 1 1 .708-.708l3 3a.5.5 0 0 1 0 .708l-3 3a.5.5 0 0 1-.708-.708L10.293 8.5H4.5A.5.5 0 0 1 4 8z"/> </svg> <a href=#additionalProperties onclick="anchorLink('additionalProperties')">additionalProperties</a></div><span class="badge badge-dark value-type">Type: object</span><br> </div> </div> </div> </div> <footer> <p class=generated-by-footer>Generated using <a href=https://github.com/coveooss/json-schema-for-humans>json-schema-for-humans</a> on 2021-09-08 at 22:43:01 +0100</p> </footer> </body> </html>
Loading

0 comments on commit d3b129e

Please sign in to comment.