On-board documentation is a key feature for Gadget. There are several facets to the documentation project:

• Easy to write documentation
  • The lower the barrier to writing it, the more likely it is to get written
• Wide availability
  
  • Gadget is just a Linux box. Almost all of the documentation will have relevance outside of Gadget boards.
• Uniformity
  
  • I want the documentation to look and act the same whether it's viewed on-board or online
• Readable source code

With these constraints in mind, I decided that Markdown-based documentation was the right choice. It's easy to write, the source is almost as pretty as the rendered version and it's ubiquitous (if everyone knows it, everyone can help me write it, right?)

I want Gadget to be a light-weight as possible, so I decided to write a very simple web-server to render and serve the Markdown documentation.

I chose golang to implement it as it has a very powerful HTTP library built in, and its static linkage makes for easy deployment to the target without needing to do a whole bunch of configuration - single executable, run it with some arguments, lovely jubbly. This means I can just as easily run it on my development machine without needing to keep two web server configurations in sync (one on the target and one on the host).

The result is docserver, its less than 500 lines of Go and will render and serve Markdown pages with a minimum of fuss.

With this in place, I can set about writing the documentation to accompany my proof-of-concept dogfooding phase of the project.

Example docserver session:

$ docserver --root . --template private/md_template.html --filter '^private' --error-template=private/error_template.html
2016/03/19 17:14:40 Using template: private/md_template.html
2016/03/19 17:14:40 Using error-template: private/error_template.html
2016/03/19 17:14:40 Document root: .
2016/03/19 17:14:40 Adding filter: ^private
2016/03/19 17:14:40 Serving on ':8000'
2016/03/19 17:14:43 From: 127.0.0.1:52164 -> GET 127.0.0.1:8000/avrisp/index.md
2016/03/19 17:14:43 |-> Resolving: avrisp/index.md
2016/03/19 17:14:43 |-> Resolved: avrisp/index.md
2016/03/19 17:14:43 `-> Serving markdown: avrisp/index.md
2016/03/19 17:14:43 From: 127.0.0.1:52164 -> GET 127.0.0.1:8000/style/github-flavored-markdown.css
2016/03/19 17:14:43 |-> Resolving: style/github-flavored-markdown.css
2016/03/19 17:14:43 |-> Resolved: style/github-flavored-markdown.css
2016/03/19 17:14:43 `-> Serving file: style/github-flavored-markdown.css
2016/03/19 17:14:43 From: 127.0.0.1:52166 -> GET 127.0.0.1:8000/style/octicons/octicons.css
2016/03/19 17:14:43 |-> Resolving: style/octicons/octicons.css
2016/03/19 17:14:43 From: 127.0.0.1:52168 -> GET 127.0.0.1:8000/style/gadget-doc.css
2016/03/19 17:14:43 |-> Resolved: style/octicons/octicons.css
2016/03/19 17:14:43 `-> Serving file: style/octicons/octicons.css
2016/03/19 17:14:43 |-> Resolving: style/gadget-doc.css
2016/03/19 17:14:43 |-> Resolved: style/gadget-doc.css
2016/03/19 17:14:43 `-> Serving file: style/gadget-doc.css
2016/03/19 17:14:43 From: 127.0.0.1:52170 -> GET 127.0.0.1:8000/avrisp/isp_pins.png
2016/03/19 17:14:43 |-> Resolving: avrisp/isp_pins.png
2016/03/19 17:14:43 |-> Resolved: avrisp/isp_pins.png
2016/03/19 17:14:43 `-> Serving file: avrisp/isp_pins.png
2016/03/19 17:14:43 From: 127.0.0.1:52170 -> GET 127.0.0.1:8000/avrisp/avr_isp.png
2016/03/19 17:14:43 |-> Resolving: avrisp/avr_isp.png
2016/03/19 17:14:43 |-> Resolved: avrisp/avr_isp.png
2016/03/19 17:14:43 `-> Serving file: avrisp/avr_isp.png
2016/03/19 17:14:43 From: 127.0.0.1:52170 -> GET 127.0.0.1:8000/style/octicons/octicons.woff
2016/03/19 17:14:43 |-> Resolving: style/octicons/octicons.woff
2016/03/19 17:14:43 |-> Resolved: style/octicons/octicons.woff
2016/03/19 17:14:43 `-> Serving file: style/octicons/octicons.woff

Rendered Markdown page: