Re: [MERGE] 1781 Reorganize and improve docs

[Filippo Fadda <fi...@programmazione.it>]

Did you commit my last changes? I had fix several typos and formatting issues.

Bye

-Filippo

On Sep 28, 2013, at 2:48 PM, Alexander Shorin wrote:

> 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 (:
> 
> --
> ,,,^..^,,,

Re: [MERGE] 1781 Reorganize and improve docs

[Filippo Fadda <fi...@programmazione.it>]

I did a second PR, I'm not sure you merged it.

Sent from my iPhone

On 01/ott/2013, at 18:53, Alexander Shorin <kx...@gmail.com> wrote:

> On Tue, Oct 1, 2013 at 8:49 PM, Filippo Fadda
> <fi...@programmazione.it> wrote:
>> Did you commit my last changes? I had fix several typos and formatting issues.
> 
> Sorry, could you remind me which one? Your changes about MacOS
> installation are committed, that's I could say with sure.
> 
> --
> ,,,^..^,,,

Re: [MERGE] 1781 Reorganize and improve docs

[Alexander Shorin <kx...@gmail.com>]

On Tue, Oct 1, 2013 at 8:49 PM, Filippo Fadda
<fi...@programmazione.it> wrote:
> Did you commit my last changes? I had fix several typos and formatting issues.

Sorry, could you remind me which one? Your changes about MacOS
installation are committed, that's I could say with sure.

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