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: https://git-wip-us.apache.org/repos/asf?p=couchdb.git;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 https://github.com/apache/couchdb/blob/1781-reorganize-and-improve-docs/share/doc/ext/httpdomain.py 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 http://www.cmlenz.net/archives/2007/10/couchdb-joins - Externals API http://davispj.com/2010/09/26/new-couchdb-externals-api.html - Replication protocol http://www.dataprotocols.org/en/latest/couchdb_replication.html === Deprecates and/or supersedes next Wiki pages - http://wiki.apache.org/couchdb/Introduction - http://wiki.apache.org/couchdb/Installing_on_FreeBSD - http://wiki.apache.org/couchdb/Installing_on_OSX - http://wiki.apache.org/couchdb/Installing_on_Gentoo - http://wiki.apache.org/couchdb/Building_from_source_on_Windows - http://wiki.apache.org/couchdb/Building_The_Source_On_Nix - http://wiki.apache.org/couchdb/Verify_and_Test_Your_Installation - http://wiki.apache.org/couchdb/Getting_started_with_Futon - http://wiki.apache.org/couchdb/Technical%20Overview - http://wiki.apache.org/couchdb/Using_Views - http://wiki.apache.org/couchdb/Introduction_to_CouchDB_views - http://wiki.apache.org/couchdb/HTTP_view_API - http://wiki.apache.org/couchdb/EnableErlangViews - http://wiki.apache.org/couchdb/CouchIn15Minutes - http://wiki.apache.org/couchdb/Reference - http://wiki.apache.org/couchdb/Complete_HTTP_API_Reference and every page it references - http://wiki.apache.org/couchdb/Performance - http://wiki.apache.org/couchdb/URI_templates - http://wiki.apache.org/couchdb/HTTP_status_list - http://wiki.apache.org/couchdb/Replication - http://wiki.apache.org/couchdb/Compaction - http://wiki.apache.org/couchdb/Runtime_Statistics - http://wiki.apache.org/couchdb/Virtual_Hosts - http://wiki.apache.org/couchdb/ExternalProcesses - http://wiki.apache.org/couchdb/Setting_up_an_Admin_account - http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API - http://wiki.apache.org/couchdb/HTTP_database_API - http://wiki.apache.org/couchdb/HTTP_view_API - http://wiki.apache.org/couchdb/Rewriting_urls - http://wiki.apache.org/couchdb/Introduction_to_CouchDB_views - http://wiki.apache.org/couchdb/CommonJS_Modules - http://wiki.apache.org/couchdb/View_collation - http://wiki.apache.org/couchdb/View_server - http://wiki.apache.org/couchdb/Built-In_Reduce_Functions - http://wiki.apache.org/couchdb/Formatting_with_Show_and_List - http://wiki.apache.org/couchdb/HTTP_Document_API - http://wiki.apache.org/couchdb/Configurationfile_couch.ini - http://wiki.apache.org/couchdb/Breaking_changes - http://wiki.apache.org/couchdb/How_to_page_through_results - http://wiki.apache.org/couchdb/How_to_enable_SSL - http://wiki.apache.org/couchdb/EnableErlangViews - http://wiki.apache.org/couchdb/Performance - http://wiki.apache.org/couchdb/CORS + 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 outdated) === 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 (: -- ,,,^..^,,,
