On Tue, Oct 28, 2014 at 12:52 AM, Joan Touzet <[email protected]> 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. -- ,,,^..^,,,
