couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alexander Shorin <kxe...@gmail.com>
Subject Re: Documentation framework: slate + quilter?
Date Tue, 28 Oct 2014 07:31:03 GMT
On Tue, Oct 28, 2014 at 12:52 AM, Joan Touzet <joant@lrtw.org> wrote:
>   * Self-hosted documentation. Why aren't we doing this yet?

Sphinx docs could be hosted on CouchDB - I always did that to provide
review examples. We're not doing this because we don't have own
CouchDB server on couchdb.apache.org - the only was from IrisCouch,
but those is dead now. Current position against self-hosting on
CouchDB was shaped in form "RTD doing this fine and we don't need to
care about hosting problems. KISS.".  To change this, we need 1)
CouchDB host 2) couchapp tool 3) small script to fix underscore names
in output static html build - problem solved.

>   * Built-in examples in many languages. Yum!

The problem I see with slate is that examples aren't useful in context
to show how CouchDB API really works since there are no complete
request/response descriptions, only payload data. Headers matters, you
know, as like as exact output format since CouchDB loves line-based
protocols. Since CouchDB API is HTTP-driven, it should be described in
HTTP examples. How use it via language X is a question of more high
level description.

Also:
How do you plan to test these examples to be sure that they are even
works and all does the same things? Plain HTTP request/response
hardly, but possible; multiple languages examples will require to
setup quite more complex environment.

Which CouchDB clients will you recommend to work with CouchDB through
these examples and why these? Currently, we are quite neutral in
question of tools for working with CouchDB, but I don't think we
should show how to make requests to CouchDB using Python's builtin
urllib.

>   * Markdown driven (if you <3 .md)

Markdown is not documentation markup. It's used for HTML generation
and was invented for solving this problem unlike reStructured Text.
We'd discussed md vs rst on the very first days when Couchbase docs
get to be imported - it's easy to start with markdown, but it's not
possible to move forward with (localization, indexing,
crossreferences, version tags, glossary, search, customization and
more and more).

P.S. Bug report: current layout looks awesome on 22' monitor, but
tables are completely broken for 13' one.

--
,,,^..^,,,

Mime
View raw message