couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Alexander Shorin <>
Subject [MERGE] 1781 Reorganize and improve docs
Date Sat, 28 Sep 2013 12:48:10 GMT
Hi devs!

There was big docs merge from 1781-reorganize-and-improve-docs branch
into the master branch. What's happened?

=== Changes

- New homepage. Looks a bit Pythonic, but less confusing as huge TOC
tree does and this is temporary solution until redesign
- Better introduction into CouchDB
- Base installation guides
- Rewritten HTTP API reference
- Complete configuration reference
- Query server protocol definition
- Replication protocol definition and conflicts resolution
- Easy PR via GitHub from ReadTheDoc service
- Rich guide to views and others design functions
- Reserved section for Fauxton docs
- Maintenance routines: compaction, security, performance, backups and
others everyday routines

=== Source directory layout (share/doc/src/)

- api
HTTP API reference grouped by target resource: server, database,
document and design document.

- config
Configuration reference grouped by propose: auth contains every
section that tweaks authentication routines (admins, couch_http_auth,
oauth), http - everything for HTTP layer (httpd, ssl, vhosts) etc.
This chapter not only for config options descriptions, but also for
guides about how configuration things are works or need to be setted
up (see ssl and admins).

- couchapp
Need to admit, that CouchApp term is de-facto notable and defines
self-hosted applications by CouchDB. This chapter is about design
documents, design functions and how to use them effectively in real
world. I called it couchapp instead of ddoc or something because,
actually and suddenly, CouchDB doesn't ships with any tools to manage
and develop design documents in the Relax way. To make something
simple it's ok to go with Futon, but for real apps you will eventually
use couchapp or erica project. Hope someday erica will be a part of
CouchDB and there we can set more stuff about it.

- cve
CVE information for referencing from release notes and not only.

- fauxton
Fauxton docs. How to build, use, make addons, tweak, manage and so on.
Currently there just imported readme and addons stuff, but hope to see
Fauxton api and docs there

- install
Installation guides for various OS

- intro
Introduction into CouchDB. Where users meets with every basic bit of
CouchDB. Mostly based on Guide to CouchDB content.

- maintenance
Is about how to make CouchDB existed instance feel live and well.

- query-server
Query server related stuff for developers.

- replication
All about replication.

- whatsnew
Release notes.

Reversed for TODO:
- dev: CouchDB internals for developers. How it works, how to hack it,
file formats, modules API, extending etc. Erlang users oriented stuff.
- thirdparty: Third-party projects. Do we promote active, stable,
popular and useful projects that improves CouchDB experience like
Erica, CouchDB-Lucene, ElasticSearch, Geocouch etc.?
- tutorial: While the intro chapter is about introduction and overview
of CouchDB, tutorial will be the functional step-by-step guide focused
on meeting API by using implementation of some single tutorial project
as an example.

=== New API Reference Syntax

Check out for an example:;a=blob;f=share/doc/src/api/document/common.rst;h=6687ebce090d4f477371234c89e93c5da62bf72b;hb=HEAD#l65

Request items are marked with `<` prefix, response one - with `>`.
Certainly, any prefix is omitted for things that are used only in
request (query params) and response (HTTP code). To simplify reading,
all endpoints descriptions are written in the next format:

<request headers
query parameters
<request payload
>response headers
>response body
http status code

=== Covers around 20 issues

COUCHDB-906: Please offer offline downloadable documentation
COUCHDB-1168:The multipart API is not documented
COUCHDB-1254: Document design and view options
COUCHDB-1538: Actually explain configuration options in configuring [reference]
COUCHDB-1539: Write some documentation on (writing) views [views]
COUCHDB-1540: Expand view documentation in reference (skipping and
grouping) [api/design]
COUCHDB-1543: Fill out db maintenance reference (?) [api/dbmaint]
COUCHDB-1544: Fill out authentication reference [api/authn]
COUCHDB-1545: Document missing APIs [api/database]
COUCHDB-1546: Add table with list of APIs [api/design]
COUCHDB-1657: View Server description does not explain how Update
Handlers must be implmented
COUCHDB-1781: Reorganize/improve docs articles
COUCHDB-1820: Collation not in official documentation
COUCHDB-1822: Authentication (particularly _users database) not
adequately covered in official documentation
COUCHDB-1823: Automatic compaction not in official documentation
COUCHDB-1824: Official documentation of replication algorithm?
COUCHDB-1847: Automatic compaction not in official documentation
COUCHDB-1849: View generation options not in official docs
COUCHDB-1850: Documentation missing view emit _id/_rev tricks for
?include_docs=true details
COUCHDB-1857:_changes API reference doesn't mention the eventsource feed
COUCHDB-1858: X-Couch-Full-Commit is not mentioned in _bulk_docs API
COUCHDB-1864: Use sphinx-httpdomain for HTTP API reference
COUCHDB-1892: Documentation for POST /db/_bulk_docs needs TLC

=== External stuff

- Modified sphinx-httpdomain extension
  No forward compatibility with mainsteam: we're using own, shorted
and nicer syntax.

- CouchDB: The Definitive Guide
  Chapters: 1-9, 16, 17(merged with wiki article), 21, 22, 24 (partially)

- Joins in CouchDB

- Externals API

- Replication protocol

=== Deprecates and/or supersedes next Wiki pages

- and every
page it references
+ may be some others, but I was unable to reach them in three clicks
from main page (I suppose such pages aren't popular and heavy

=== What this merge does not?

Docs are still not provides fluid content that allows reader to
incrementally meet with CouchDB and increase his knowledge about step
by step like Guide to CouchDB does. Currently they looks as collection
of independent articles that was written by different people using
different style and mostly usable as reference material, not good
reading on rainy evening sitting on the couch before the fireplace.
But whoever reads the FM?(:

=== What's next?

- Practical tutorial
- Troubleshooting
- More internals
- More installation guides
- Better articles flow
- Redesign to match site/fauxton style
- Nicer and printable PDF build (yes, currently you better to print
single-paged html file as PDF from your browser)

but all this is for another commits and not for another long-living
feature branch (:


View raw message