Move parameter doc to use tooltips generated using the online documentation (#2059)

* prework

* add tooltips

* .

* Update build.yaml

* remove tooltip link and embed it directly

* embedd tooltip directly

* .

* .

* .

* .

* .

* .

* .

* .

* .

* .

* fix disabled tooltips

* fix disabled tooltips

* renamed Parameter in UI, added units, fixed labels

* .

* .

* .

---------

Co-authored-by: CaCO3 <caco@ruinelli.ch>
This commit is contained in:
CaCO3
2023-02-24 18:36:26 +01:00
committed by GitHub
parent 2c1a7f4c9e
commit b0de37b762
14 changed files with 7662 additions and 460 deletions

View File

@@ -70,15 +70,24 @@ jobs:
#run: echo "Testing... ${{ github.ref_name }}, ${{ steps.vars.outputs.sha_short }}" > ./sd-card/html/version.txt; mkdir -p ./code/.pio/build/esp32cam/; cd ./code/.pio/build/esp32cam/; echo "${{ steps.vars.outputs.sha_short }}" > firmware.bin; cp firmware.bin partitions.bin; cp firmware.bin bootloader.bin # Testing
run: cd code; platformio run --environment esp32cam
- name: Prepare Web UI (copy data from repo and update hashes in all files)
- name: Prepare Web UI (copy data from repo, generate tooltip pages and update hashes in all files)
run: |
rm -rf ./html
mkdir html
cp ./sd-card/html/* ./html/
cp -r ./sd-card/html/* ./html/
python -m pip install markdown
mkdir html/param-tooltips
cd tools/parameter-tooltip-generator
bash generate-param-doc-tooltips.sh
cd ../..
cp -r ./sd-card/html/* ./html/
echo "Replacing variables..."
cd html; find . -type f -exec sed -i 's/$COMMIT_HASH/${{ steps.vars.outputs.sha_short }}/g' {} \;
#########################################################################################
## Pack for Update
#########################################################################################
@@ -86,7 +95,7 @@ jobs:
# New OTA concept
# update__version.zip file with following content:
# - /firmware.bin
# - (optional) /html/*
# - (optional) /html/* (inkl. subfolders)
# - (optional) /config/*.tfl
runs-on: ubuntu-latest
needs: build
@@ -149,7 +158,7 @@ jobs:
# New Remote Setup concept
# remote_setup__version.zip file with following content:
# - /firmware.bin
# - /html/*
# - /html/* (inkl. subfolders)
# - /config/*
runs-on: ubuntu-latest
needs: build

3
.gitignore vendored
View File

@@ -23,3 +23,6 @@ CTestTestfile.cmake
_deps
code/edgeAI.code-workspace
.DS_Store
tools/parameter-tooltip-generator/html
tools/parameter-tooltip-generator/AI-on-the-edge-device-docs
sd-card/html/param_tooltips

File diff suppressed because it is too large Load Diff

BIN
sd-card/html/help.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.8 KiB

View File

@@ -0,0 +1 @@
.hljs{display:block;overflow-x:auto;padding:.5em;color:#333;background:#f8f8f8}.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:700}.hljs-literal,.hljs-number,.hljs-tag .hljs-attr,.hljs-template-variable,.hljs-variable{color:teal}.hljs-doctag,.hljs-string{color:#d14}.hljs-section,.hljs-selector-id,.hljs-title{color:#900;font-weight:700}.hljs-subst{font-weight:400}.hljs-class .hljs-title,.hljs-type{color:#458;font-weight:700}.hljs-attribute,.hljs-name,.hljs-tag{color:navy;font-weight:400}.hljs-link,.hljs-regexp{color:#009926}.hljs-bullet,.hljs-symbol{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:700}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}

View File

@@ -0,0 +1 @@
The files in this folder are directly copied from the generated mkdocs site folder.

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,187 @@
/*
* Wrap inline code samples otherwise they shoot of the side and
* can't be read at all.
*
* https://github.com/mkdocs/mkdocs/issues/313
* https://github.com/mkdocs/mkdocs/issues/233
* https://github.com/mkdocs/mkdocs/issues/834
*/
.rst-content code {
white-space: pre-wrap;
word-wrap: break-word;
padding: 2px 5px;
}
/**
* Make code blocks display as blocks and give them the appropriate
* font size and padding.
*
* https://github.com/mkdocs/mkdocs/issues/855
* https://github.com/mkdocs/mkdocs/issues/834
* https://github.com/mkdocs/mkdocs/issues/233
*/
.rst-content pre code {
white-space: pre;
word-wrap: normal;
display: block;
padding: 12px;
font-size: 12px;
}
/**
* Fix code colors
*
* https://github.com/mkdocs/mkdocs/issues/2027
*/
.rst-content code {
color: #E74C3C;
}
.rst-content pre code {
color: #000;
background: #f8f8f8;
}
/*
* Fix link colors when the link text is inline code.
*
* https://github.com/mkdocs/mkdocs/issues/718
*/
a code {
color: #2980B9;
}
a:hover code {
color: #3091d1;
}
a:visited code {
color: #9B59B6;
}
/*
* The CSS classes from highlight.js seem to clash with the
* ReadTheDocs theme causing some code to be incorrectly made
* bold and italic.
*
* https://github.com/mkdocs/mkdocs/issues/411
*/
pre .cs, pre .c {
font-weight: inherit;
font-style: inherit;
}
/*
* Fix some issues with the theme and non-highlighted code
* samples. Without and highlighting styles attached the
* formatting is broken.
*
* https://github.com/mkdocs/mkdocs/issues/319
*/
.rst-content .no-highlight {
display: block;
padding: 0.5em;
color: #333;
}
/*
* Additions specific to the search functionality provided by MkDocs
*/
.search-results {
margin-top: 23px;
}
.search-results article {
border-top: 1px solid #E1E4E5;
padding-top: 24px;
}
.search-results article:first-child {
border-top: none;
}
form .search-query {
width: 100%;
border-radius: 50px;
padding: 6px 12px; /* csslint allow: box-model */
border-color: #D1D4D5;
}
/*
* Improve inline code blocks within admonitions.
*
* https://github.com/mkdocs/mkdocs/issues/656
*/
.rst-content .admonition code {
color: #404040;
border: 1px solid #c7c9cb;
border: 1px solid rgba(0, 0, 0, 0.2);
background: #f8fbfd;
background: rgba(255, 255, 255, 0.7);
}
/*
* Account for wide tables which go off the side.
* Override borders to avoid weirdness on narrow tables.
*
* https://github.com/mkdocs/mkdocs/issues/834
* https://github.com/mkdocs/mkdocs/pull/1034
*/
.rst-content .section .docutils {
width: 100%;
overflow: auto;
display: block;
border: none;
}
/*
* Without the following amendments, the navigation in the theme will be
* slightly cut off. This is due to the fact that the .wy-nav-side has a
* padding-bottom of 2em, which must not necessarily align with the font-size of
* 90 % on the .rst-current-version container, combined with the padding of 12px
* above and below. These amendments fix this in two steps: First, make sure the
* .rst-current-version container has a fixed height of 40px, achieved using
* line-height, and then applying a padding-bottom of 40px to this container. In
* a second step, the items within that container are re-aligned using flexbox.
*
* https://github.com/mkdocs/mkdocs/issues/2012
*/
.wy-nav-side {
padding-bottom: 40px;
}
/*
* The second step of above amendment: Here we make sure the items are aligned
* correctly within the .rst-current-version container. Using flexbox, we
* achieve it in such a way that it will look like the following:
*
* [No repo_name]
* Next >> // On the first page
* << Previous Next >> // On all subsequent pages
*
* [With repo_name]
* <repo_name> Next >> // On the first page
* <repo_name> << Previous Next >> // On all subsequent pages
*
* https://github.com/mkdocs/mkdocs/issues/2012
*/
.rst-versions .rst-current-version {
padding: 0 12px;
display: flex;
font-size: initial;
justify-content: space-between;
align-items: center;
line-height: 40px;
}
/*
* Please note that this amendment also involves removing certain inline-styles
* from the file ./mkdocs/themes/readthedocs/versions.html.
*
* https://github.com/mkdocs/mkdocs/issues/2012
*/
.rst-current-version span {
flex: 1;
text-align: center;
}

View File

@@ -0,0 +1,80 @@
"""
Grab all parameter files (markdown) and convert them to html files
"""
import os
import glob
import markdown
parameterDocsFolder = "AI-on-the-edge-device-docs/param-docs/parameter-pages"
docsMainFolder = "../../sd-card/html"
configPage = "edit_config_param.html"
imagesFolder = "param_tooltips"
htmlTooltipPrefix = """
<div class="rst-content"><div class="tooltip"><img src="help.png" width="32px"><span class="tooltiptext">
"""
htmlTooltipSuffix = """
</span></div></div>
"""
folders = sorted( filter( os.path.isdir, glob.glob(parameterDocsFolder + '/*') ) )
def generateHtmlTooltip(section, parameter, markdownFile):
# print(section, parameter, markdownFile)
with open(markdownFile, 'r') as markdownFileHandle:
markdownFileContent = markdownFileHandle.read()
markdownFileContent = markdownFileContent.replace("# ", "### ") # Move all headings 2 level down
htmlTooltip = markdown.markdown(markdownFileContent, extensions=['admonition'])
# Make all links to be opened in a new page
htmlTooltip = htmlTooltip.replace("a href", "a target=_blank href")
# Add custom styles
htmlTooltip = htmlTooltip.replace("<h3>", "<h3 style=\"margin: 0\">")
# Update image paths and copy images to right folder
if "../img/" in htmlTooltip:
htmlTooltip = htmlTooltip.replace("../img/", imagesFolder + "/")
htmlTooltip = htmlTooltipPrefix + htmlTooltip + htmlTooltipSuffix
# Add the tooltip to the config page
with open(docsMainFolder + "/" + configPage, 'r') as configPageHandle:
configPageContent = configPageHandle.read()
# print("replacing $TOOLTIP_" + section + "_" + parameter + " with the tooltip content...")
configPageContent = configPageContent.replace("<td>$TOOLTIP_" + section + "_" + parameter + "</td>", "<td>" + htmlTooltip + "</td>")
with open(docsMainFolder + "/" + configPage, 'w') as configPageHandle:
configPageHandle.write(configPageContent)
print("Generating Tooltips...")
"""
Generate a HTML tooltip for each markdown page
"""
for folder in folders:
folder = folder.split("/")[-1]
files = sorted(filter(os.path.isfile, glob.glob(parameterDocsFolder + "/" + folder + '/*')))
for file in files:
if not ".md" in file: # Skip non-markdown files
continue
parameter = file.split("/")[-1].replace(".md", "")
parameter = parameter.replace("<", "").replace(">", "")
generateHtmlTooltip(folder, parameter, file)
"""
Copy images to main folder
"""
os.system("cp " + parameterDocsFolder + "/img/* " + docsMainFolder + "/" + imagesFolder)

View File

@@ -0,0 +1,15 @@
#!/bin/bash
# Checkout the documentation reposo we can extract the parameter documentation
if [ -d "AI-on-the-edge-device-docs" ] ; then
# Repo already checked out, pull it
cd AI-on-the-edge-device-docs
git checkout main
git pull
cd ..
else
# Repos folde ris missing, clone it
git clone https://github.com/jomjol/AI-on-the-edge-device-docs.git
fi
python generate-param-doc-tooltips.py

View File

@@ -0,0 +1 @@
.hljs{display:block;overflow-x:auto;padding:.5em;color:#333;background:#f8f8f8}.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:700}.hljs-literal,.hljs-number,.hljs-tag .hljs-attr,.hljs-template-variable,.hljs-variable{color:teal}.hljs-doctag,.hljs-string{color:#d14}.hljs-section,.hljs-selector-id,.hljs-title{color:#900;font-weight:700}.hljs-subst{font-weight:400}.hljs-class .hljs-title,.hljs-type{color:#458;font-weight:700}.hljs-attribute,.hljs-name,.hljs-tag{color:navy;font-weight:400}.hljs-link,.hljs-regexp{color:#009926}.hljs-bullet,.hljs-symbol{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:700}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}

View File

@@ -0,0 +1 @@
The files in this folder are directly copied from the generated mkdocs site folder.

File diff suppressed because one or more lines are too long

View File

@@ -0,0 +1,191 @@
/*
* Wrap inline code samples otherwise they shoot of the side and
* can't be read at all.
*
* https://github.com/mkdocs/mkdocs/issues/313
* https://github.com/mkdocs/mkdocs/issues/233
* https://github.com/mkdocs/mkdocs/issues/834
*/
.rst-content code {
white-space: pre-wrap;
word-wrap: break-word;
padding: 2px 5px;
}
/**
* Make code blocks display as blocks and give them the appropriate
* font size and padding.
*
* https://github.com/mkdocs/mkdocs/issues/855
* https://github.com/mkdocs/mkdocs/issues/834
* https://github.com/mkdocs/mkdocs/issues/233
*/
.rst-content pre code {
white-space: pre;
word-wrap: normal;
display: block;
padding: 12px;
font-size: 12px;
}
/**
* Fix code colors
*
* https://github.com/mkdocs/mkdocs/issues/2027
*/
.rst-content code {
color: #E74C3C;
}
.rst-content pre code {
color: #000;
background: #f8f8f8;
}
/*
* Fix link colors when the link text is inline code.
*
* https://github.com/mkdocs/mkdocs/issues/718
*/
a code {
color: #2980B9;
}
a:hover code {
color: #3091d1;
}
a:visited code {
color: #9B59B6;
}
/*
* The CSS classes from highlight.js seem to clash with the
* ReadTheDocs theme causing some code to be incorrectly made
* bold and italic.
*
* https://github.com/mkdocs/mkdocs/issues/411
*/
pre .cs, pre .c {
font-weight: inherit;
font-style: inherit;
}
/*
* Fix some issues with the theme and non-highlighted code
* samples. Without and highlighting styles attached the
* formatting is broken.
*
* https://github.com/mkdocs/mkdocs/issues/319
*/
.rst-content .no-highlight {
display: block;
padding: 0.5em;
color: #333;
}
/*
* Additions specific to the search functionality provided by MkDocs
*/
.search-results {
margin-top: 23px;
}
.search-results article {
border-top: 1px solid #E1E4E5;
padding-top: 24px;
}
.search-results article:first-child {
border-top: none;
}
form .search-query {
width: 100%;
border-radius: 50px;
padding: 6px 12px; /* csslint allow: box-model */
border-color: #D1D4D5;
}
/*
* Improve inline code blocks within admonitions.
*
* https://github.com/mkdocs/mkdocs/issues/656
*/
.rst-content .admonition code {
color: #404040;
border: 1px solid #c7c9cb;
border: 1px solid rgba(0, 0, 0, 0.2);
background: #f8fbfd;
background: rgba(255, 255, 255, 0.7);
}
/*
* Account for wide tables which go off the side.
* Override borders to avoid weirdness on narrow tables.
*
* https://github.com/mkdocs/mkdocs/issues/834
* https://github.com/mkdocs/mkdocs/pull/1034
*/
.rst-content .section .docutils {
width: 100%;
overflow: auto;
display: block;
border: none;
}
td, th {
border: 1px solid #e1e4e5 !important; /* csslint allow: important */
border-collapse: collapse;
}
/*
* Without the following amendments, the navigation in the theme will be
* slightly cut off. This is due to the fact that the .wy-nav-side has a
* padding-bottom of 2em, which must not necessarily align with the font-size of
* 90 % on the .rst-current-version container, combined with the padding of 12px
* above and below. These amendments fix this in two steps: First, make sure the
* .rst-current-version container has a fixed height of 40px, achieved using
* line-height, and then applying a padding-bottom of 40px to this container. In
* a second step, the items within that container are re-aligned using flexbox.
*
* https://github.com/mkdocs/mkdocs/issues/2012
*/
.wy-nav-side {
padding-bottom: 40px;
}
/*
* The second step of above amendment: Here we make sure the items are aligned
* correctly within the .rst-current-version container. Using flexbox, we
* achieve it in such a way that it will look like the following:
*
* [No repo_name]
* Next >> // On the first page
* << Previous Next >> // On all subsequent pages
*
* [With repo_name]
* <repo_name> Next >> // On the first page
* <repo_name> << Previous Next >> // On all subsequent pages
*
* https://github.com/mkdocs/mkdocs/issues/2012
*/
.rst-versions .rst-current-version {
padding: 0 12px;
display: flex;
font-size: initial;
justify-content: space-between;
align-items: center;
line-height: 40px;
}
/*
* Please note that this amendment also involves removing certain inline-styles
* from the file ./mkdocs/themes/readthedocs/versions.html.
*
* https://github.com/mkdocs/mkdocs/issues/2012
*/
.rst-current-version span {
flex: 1;
text-align: center;
}