This is pretty much a direct follow-up to my last post. This is for how I’m generating the documentation for my camera trigger project. I’m making more progress on the documentation then the actual project, so I’m just like the big companies.
Markdown
I’m writing the documentation in markdown. This means learning markdown. Here’s what you need to learn markdown: https://github.com/ahrencode/Miscellaneous/raw/master/markdown-cheatsheet.png. Its not very hard.
The reason for using markdown is because github doesn’t support HTML for markdown. I think it I figured out why, but its still kind of annoying. (I believe it has to do with the proper tags for starting an html project, css styles, etc.).
HTML
Who doesn’t love HTML? It lets you make things look pretty. So does latex, etc. but I’m not wanting to learn that right now. I’m using pandoc to generate my html. You can use the original daring fireball markdown generator if you would like. But using pandoc allows you specify a style sheet for you to make the html render from. The command I’m using is
pandoc file-name -c stylesheet.css --html5 --output=file-name.html --to=html --from=markdown
I actually just have a function in my bashrc:
function markdowntoprettyhtml() { pandoc $1 -c stylesheet.css --html5 --output=$1.html --to=html --from=markdown ;}
The other pretty much standard documentation format is PDF. I’m generating that from my HTML file using wkhtmltopdf. To build I cloned the repository, then did git checkout 0.9.6 && qmake-qt4 && make && cp wkhtmltopdf to ~/compiled. The ~/compiled folder is in my path. I would have liked to done a symbolic link but I couldn’t execute wkhtmltopdf after I did that.
Now, I’m using this command wkhtmltopdf input-file outputfile.pdf.
The reason I’m using this is because although pandoc has its own pdf converter, I don’t want to use the pandoc styling, I want to use the styling in the HTML file. And I’m not writing another template when I already have the styling done in css.
You can checkout (literally!) the results on the beta branch for my camera trigger.
And . . .
A few one liners to tie it all together:
function markdownview ( ) { perl ~/compiled/Markdown.pl --html4tags $1 ;}
function markdowntohtml ( ) { pandoc $1 -c stylesheet.css --html5 --output=$1.html --to=html --from=markdown ;}
function markdowntopdf ( ) { pandoc $1 -c stylesheet.css --html5 --output $1.html.generate --to=html --from=markdown && wkhtmltopdf $1.html.generate $1.pdf && rm $1.html.gernerate ;}
function make-documentation () { markdowntohtml $1 && markdowntopdf $1; }
Enjoy!
One other note: If you open the HTML in firefox you’ll see that I’ve got some @font-face love going on. You’ll see I’m also pulling them from my website as well. What you might not notice is that if you to do this yourself without some setup, it fails. It has to to with Cross Origin Response Sharing and the way firefox implements it. You can check this page for a succent explanation of why. Its under “Firefox overview.” The easiest way to fix this problem is to create a .htacces file with the following line: Header set Access-Control-Allow-Origin * to the folder containg your webfonts.