couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joan Touzet <jo...@lrtw.org>
Subject Documentation framework: slate + quilter?
Date Mon, 27 Oct 2014 21:52:20 GMT
At a previous CouchDB IRC meeting I mentioned that Cloudant had worked
up a new approach to documentation, capable of including per-language
examples AND being hosted in CouchDB itself. I'd like to share the
links, get feedback and see if the community is interested in helping
develop it further.

Before anyone thinks I am taking credit here, I'm not - I'm just the
messenger. This exists solely through the good work of Diana Thayer
(@garbados), Brad Noble (@bradnoble), Kim Stebel (@kimstebel), Sean
Barclay (@seanbarclay) and others whose names escape me at present.
Thank you for getting us this far, everyone!

First, the link:

http://is.gd/cloudant_doc_rewrite

This is an extract of the Cloudant API reference docs, converted to
tripit's Slate framework, and maintained as a couchapp by garbados'
quilter tool:

https://github.com/cloudant-labs/slate
https://github.com/garbados/quilter

As you scroll through the reference, be sure to try the curl and node.js
tab links. (The http and python ones are not as complete.) The idea here
is to have the examples inline with the API reference, and to provide
them in the language of choice for developers.

Advantages:
  * Self-hosted documentation. Why aren't we doing this yet?
  * Built-in examples in many languages. Yum!
  * Markdown driven (if you <3 .md)

Disadvantages:
  * Markdown, not ReStructuredText driven (if you <3 .rst)
    * 1-time conversion to .md required
  * More tooling to support

Is this something the community would be interested in helping
build/maintain/incorporating into CouchDB?

-Joan

Mime
View raw message