Restructure param docs (#15)

* Update build-docs.yaml

* .

* moved files

* .

* Update build-docs.yaml

* Update build-docs.yaml

---------

Co-authored-by: CaCO3 <caco@ruinelli.ch>

.github/workflows/build-docs.yaml

@@ -40,7 +40,7 @@ jobs:
       - name: Store docs in gh-pages branch
         run: |
           # Update Parameter Documentation
-          cd generate-param-docs
+          cd param-docs
           python generate-param-doc-pages.py
           python concat-parameter-pages.py
           cd ..

README.md

@@ -25,12 +25,20 @@ Each page has a link on its top-right corner `Edit on GitHub` which brings you d
 1. Add a new `*.md` document in the [docs](docs) folder.
 1. Add the **filename** to the [docs/nav.yml](docs/nav.yml) at the wished position in the **Links** section.
 
-## Parameter Docs Generator
+## Parameter Documentation
-The script `generate-param-docs/generate-param-doc-pages.py` should be run whenever the [configfile](https://github.com/jomjol/AI-on-the-edge-device/blob/rolling/sd-card/config/config.ini) in the main project repo changed.
+Each parameter which is listed in the [configfile](https://github.com/jomjol/AI-on-the-edge-device/blob/rolling/sd-card/config/config.ini) in the main project repo 
-It then checks if there is a markdown file  for each of the contained parameters. if not, it generates a templated page.
+has its own description page in the folder `param-docs/parameter-pages` (grouped by the config sections).
+Those pages can be edited as needed.
+
+The script `param-docs/concat-parameter-pages.py` should be run whenever one of the pages changed.
+It then concatenates all pages into the single `../docs/Parameters.md` which gets be added to the `mkdocs` documentation.
+
+### Template Generator
+The script `param-docs/generate-param-doc-pages.py` should be run whenever a new parameter gets added to the config file.
+It then checks if there is already page for each of the parameters.
+ - If no page exists yet, a templated page gets generated.
+ - Existing pages do not get modified.
 
-The script `generate-param-docs/concat-parameter-pages.py` should be run whenever one of the parameter documentation pages changed.
-It then concatenates all parameter pages into a single `Parameters.md` which can be added to the documentation.
 
 ## Local Test
 To test it locally:

param-docs/concat-parameter-pages.py

@@ -8,12 +8,12 @@ import shutil
 import glob
 
 
-parameterDocsFolder = "parameter-docs"
+parameterDocsFolder = "parameter-pages"
 parameterOverviewFile = "../docs/Parameters.md"
 parameterOverviewTemplateFile = "./templates/overview.md"
 
 def appendParameterFile(folder, file):
-    print(folder, file)
+    #print(folder, file)
 
     with open(file, 'r') as parameterFileHandle:
         parameterDoc = parameterFileHandle.read()

param-docs/generate-param-doc-pages.py

@@ -1,6 +1,6 @@
 """
 For each parameter which can be found in the config file,
-create a markdown file with a templated contentf it does not exist yet.
+create a markdown file with a templated content it does not exist yet.
 The files are grouped in sub folders representing the config sections.
 """
 
@@ -8,12 +8,14 @@ import os
 import configparser
 import urllib.request
 
+
 configFileUrl = "https://raw.githubusercontent.com/jomjol/AI-on-the-edge-device/rolling/sd-card/config/config.ini"
 
-parameterDocsFolder = "parameter-docs"
+parameterDocsFolder = "parameter-pages"
 parameterTemplateFile = "./templates/parameter.md"
 
 # Fetch default config file from URL
+print("Fetching %r..." % configFileUrl)
 with urllib.request.urlopen(configFileUrl) as response:
    content = response.read().decode("utf-8")
 
@@ -39,7 +41,7 @@ with open(parameterTemplateFile, 'r') as parameterTemplateFileHandle:
     parameterTemplate = parameterTemplateFileHandle.read()
 
 
-
+print("For each section/parameter, check if there is already a documentation page in the folder %r..." % (os.getcwd() + "/" + parameterDocsFolder))
 for section in config:
     if section != "DEFAULT":
         #print(section)
@@ -60,6 +62,7 @@ for section in config:
                 parameterDocFile = subFolder + '/' + parameter + ".md"
 
                 if not os.path.exists(parameterDocFile): # File does not exist yet, generate template
+                    print("%r does not exit yet, generating a templated file for it" % (os.getcwd() + "/" + parameterDocFile))
                     with open(parameterDocFile, 'w') as paramFileHandle:
                         content = parameterTemplate
                         content = content.replace("$NAME", parameter)