Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add JSON Documentation & Document Generator #180

Merged
merged 13 commits into from
Sep 9, 2021
Merged

Add JSON Documentation & Document Generator #180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
d81be96
Update README.md
noursaidi May 26, 2021
e284676
Merge branch 'faucetsdn:master' into master
noursaidi Aug 11, 2021
e2b1744
Merge branch 'faucetsdn:master' into master
noursaidi Aug 31, 2021
76b554f
add schema document generator and documents
noursaidi Sep 2, 2021
6ad6fc3
Add existing descriptions from docs
noursaidi Sep 6, 2021
54b4eae
few more additions, add hashes and hash checking
noursaidi Sep 7, 2021
df5469f
change to draft 07 because we are using annotations
noursaidi Sep 7, 2021
53e3910
Delete event.html
noursaidi Sep 7, 2021
58a9a92
small fixes
noursaidi Sep 8, 2021
c8fc122
Merge branch 'docgenerator' of github.com:noursaidi/udmi into docgene…
noursaidi Sep 8, 2021
a94fe10
empty commit
noursaidi Sep 8, 2021
743420a
new line at end of testing.yaml
noursaidi Sep 8, 2021
9fde3bc
fix indent
noursaidi Sep 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/testing.yml
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop

Large diffs are not rendered by default.

1 change: 1 addition & 0 deletions gencode/docs/envelope.html
View file
Open in desktop
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