diff --git a/README.md b/README.md index 2045b4d..b2a55d9 100644 --- a/README.md +++ b/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 -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. -It then checks if there is a markdown file for each of the contained parameters. if not, it generates a templated page. +## Parameter Documentation +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 +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: diff --git a/generate-param-docs/concat-parameter-pages.py b/generate-param-docs/concat-parameter-pages.py deleted file mode 100644 index b20a7a8..0000000 --- a/generate-param-docs/concat-parameter-pages.py +++ /dev/null @@ -1,48 +0,0 @@ -""" -Grab all parameter files and concat them into a single file. -The header structure gets moved down 1 level -""" - -import os -import shutil -import glob - - -parameterDocsFolder = "parameter-docs" -parameterOverviewFile = "../docs/Parameters.md" -parameterOverviewTemplateFile = "./templates/overview.md" - -def appendParameterFile(folder, file): - print(folder, file) - - with open(file, 'r') as parameterFileHandle: - parameterDoc = parameterFileHandle.read() - parameterDoc = parameterDoc.replace("# ", "### ") # Move all headings 2 level down - - # Add parameter doc to overview page - with open(parameterOverviewFile, 'a') as overviewFileHandle: - overviewFileHandle.write(parameterDoc + "\n---\n\n") - - - -# Create templated overview markdown file -if os.path.exists(parameterOverviewFile): - os.remove(parameterOverviewFile) -shutil.copy(parameterOverviewTemplateFile, parameterOverviewFile) - -""" -Append all parameter pages in a sorted manner -""" -folders = sorted( filter( os.path.isdir, glob.glob(parameterDocsFolder + '/*') ) ) -for folder in folders: - folder = folder.split("/")[-1] -# print(folder) - - # Add section - with open(parameterOverviewFile, 'a') as overviewFileHandle: - overviewFileHandle.write("\n## [%s]\n\n" % folder) - - files = sorted(filter(os.path.isfile, glob.glob(parameterDocsFolder + "/" + folder + '/*'))) - for file in files: -# print(" %s" % file) - appendParameterFile(folder, file) diff --git a/generate-param-docs/generate-param-doc-pages.py b/generate-param-docs/generate-param-doc-pages.py deleted file mode 100644 index 6fa5f14..0000000 --- a/generate-param-docs/generate-param-doc-pages.py +++ /dev/null @@ -1,68 +0,0 @@ -""" -For each parameter which can be found in the config file, -create a markdown file with a templated contentf it does not exist yet. -The files are grouped in sub folders representing the config sections. -""" - -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" -parameterTemplateFile = "./templates/parameter.md" - -# Fetch default config file from URL -with urllib.request.urlopen(configFileUrl) as response: - content = response.read().decode("utf-8") - -lines = str(content).split("\n") - -for l in range(len(lines)): - lines[l] = lines[l].strip() + "\n" - if lines[l][0] == ";": - lines[l] = lines[l][1:] # Remove comment - -content = "".join(lines) - - -config = configparser.ConfigParser(allow_no_value=True) -config.optionxform = str # Make it case-insensitive -config.read_string(content) - -#shutil.rmtree(parameterDocsFolder) -if not os.path.exists(parameterDocsFolder): - os.mkdir(parameterDocsFolder) - -with open(parameterTemplateFile, 'r') as parameterTemplateFileHandle: - parameterTemplate = parameterTemplateFileHandle.read() - - - -for section in config: - if section != "DEFAULT": - #print(section) - - subFolder = parameterDocsFolder + "/" + section - - if not os.path.exists(subFolder): - os.mkdir(subFolder) - - for parameter in config[section]: - if not " " in parameter: # Ignore parameters with whitespaces in them (special format, not part of editable config) - value = config[section][parameter] - #print(" %s = %s" % (parameter, value)) - - """ - For each config line, create a markdown file - """ - parameterDocFile = subFolder + '/' + parameter + ".md" - - if not os.path.exists(parameterDocFile): # File does not exist yet, generate template - with open(parameterDocFile, 'w') as paramFileHandle: - content = parameterTemplate - content = content.replace("$NAME", parameter) - content = content.replace("$DEFAULT", value) - - paramFileHandle.write(content)