Moving email between @Alain and me to discourse. This is in reference to future directions for SDK documentation
On Wed, Apr 1, 2015 at 7:03 AM, Alain Cormier wrote:
BTW, I had a quick look at GitBook today and it’s awesome!
Alain
On Wed, Apr 1, 2015 at 9:59 PM, Steve Baer wrote:
Gitbook does look like a good platform to use for building our SDK reference. If you have ideas on how to set this up, I would love to see them.
-Steve
On Thu, Apr 2, 2015 at 7:25 AM, Alain Cormier wrote:
Hi Steve,
What’s great about GitBook is that you can have your documentation come from the same repo as the code you want to document (literate programming: code and docs as one). Your book can be versioned and always be in sync with releases, i.e., one version in sync with the MacRhino branch and another in sync with wip. The book pages can reference comments that are directly in the code or the code itself. I haven’t done any formatting but here’s a link to my experiment: https://www.gitbook.com/book/acormier/rhinopythondocs/details.
It wouldn’t be too bad to bring everything in from Robohelp. I could do things like:
- create a generic template from this: https://raw.githubusercontent.com/acormier/rhinopythondocs/master/linetype/IsLinetype.md and plug-in the data by parsing the docstrings (templating is built-into gitbook)
- I then can update/fix the content.
Another thing worth mentioning is the the complete gitbook toolchain is available (https://github.com/GitbookIO/gitbook) so you can build books locally and even host them yourself instead of on gitbook.com.
What do you think?
Cheers,
Alain