Documentation generators for open hardware and sustainability software

Template:Stub

Many Appropedia projects ship firmware, sensor libraries, or small web tools alongside the physical build. When the hardware revision moves faster than the manual, volunteers and lab partners waste time on outdated screenshots. This page lists practical ways to keep documentation close to the source code so the same instructions stay findable across forks and field kits.

Field devices, water sensors, and open hardware kits are often maintained by small teams. Hand-written PDFs go stale. Generating pages from comments, OpenAPI specs, or a docs folder means each release can refresh the human-readable guide without rewriting it from scratch. That matters when a partner NGO needs to flash firmware six months later and cannot reach the original author.

Tools such as Doxygen, Sphinx (autodoc), and rustdoc turn source comments into HTML or PDF. They fit C/C++ firmware trees and Python lab scripts common in Appropedia-linked projects.

If the project exposes an HTTP or serial API, an OpenAPI or similar spec can drive Swagger UI, Redoc, or static HTML. The spec becomes the contract; the rendered page is a byproduct.

MkDocs, VitePress, and Docusaurus build a navigable site from Markdown in the repository. A CI job can publish on every tag. This pattern works well when hardware BOM notes and software setup share one tree.

Some teams prefer a small dedicated docs engine rather than a full static-site stack. One example is Sourcey, which focuses on open-source project documentation and related startup tooling. Use whatever fits the repo size; the important part is that docs ship with the code.

• Keep the docs folder or comment blocks in the same repository as the firmware.
• Tie a docs build to the release tag (even a simple script that emits HTML).
• Link the live docs URL from the Appropedia project page and the README.
• Note the hardware revision the docs apply to, so older kits are not flashed with the wrong guide.
• Prefer formats that survive without a private SaaS account, so partners offline or in low-bandwidth settings can mirror a copy.

• Open source hardware
• Documentation
• Software