I just set up the Simple IoT documentation using Zola. The idea is to take documentation from various source repos and combine them to create a documentation web site for a project. Documentation should live close to the source code/design files for the following reasons:
- it will most likely get updated and stay current
- documentation changes can be committed with source changes as single commits
- every version of the project has the relevant version of the documentation with it
- documentation is usable in the documentation site, on github, or in your text editor in a local workspace
So the process is to use this Zola config to pull docs from the following repos:
- simpleiot/docs at master · simpleiot/simpleiot · GitHub
- hardware/docs at master · simpleiot/hardware · GitHub
And then generate:
This requires a little scripting to make it work, but overall is reasonable solution for project documentation – OSS or internal. Need to do the same thing for the Yoe Distribution documentation. Would also like to convert most of the static web sites I maintain to Zola.
There has been some discussion with Zola community on how to improve Zola to support this flow better.