db2a3482df
* added script to generate parameter documentation * extended readme * added templated parameter pages * Update build-docs.yaml * . * . --------- Co-authored-by: CaCO3 <caco@ruinelli.ch>
2.9 KiB
User Documentation for the AI on the Edge Device Project
This repo contains the documentation for the AI-on-the-Edge-Device Project.
How does it work
- You can edit any
*.mddocument in the docs folder. - Then create a Pull Request for it to merge it into the
mainbranch (or edit it directly in themainbranch if you have the required rights). - When it got merged, the Github Actions will re-generate the documentation and place it in the
gh-pagesbranch. This branch automatically gets populated to the public Documentation Site
Migrating existing Wiki Pages
The files from the AI-on-the-Edge-Device Wiki got exported and added to this repo. Unless the files are listed in the docs/nav.yml file, they will be listed in the assorted pages section of the left sidebar.
In the end, we should review all pages from there step by step and add them to the upper part of the navigation.
Tasks to do
- Make sure there is a top level title (#) and all other chapter headers are on lower levels (##, ###)
- Check the links in the documents
- Fetch included images and place them directly in the docs/img folder
- Rewrite to have a clear structure
Editing a page
Each page has a link on its top-right corner Edit on GitHub which brings you directly to the Github editor.
Adding new pages
- Add a new
*.mddocument in the docs folder. - Add the filename to the 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 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.
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:
-
Clone this repo
-
Install the required tools (See also .github/workflows/build-docs.yaml):
pip install --upgrade pip pip install mkdocs mkdocs-gen-files mkdocs-awesome-pages-plugin mkdocs-material pymdown-extensions -
In the main folder of the repo, call
mkdocs serve(and keep it running). This will locally generate the documentation. You can access it under http://127.0.0.1:8000/AI-on-the-edge-device-docs/Any change to the files will automatically be applied.