[Couchdb Wiki] Update of "Documentation" by DaveCottlehuber

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "Documentation" page has been changed by DaveCottlehuber:
http://wiki.apache.org/couchdb/Documentation?action=diff&rev1=8&rev2=9

  
   * The [[https://wiki.apache.org/couchdb/|CouchDB Wiki]] (you're here)
   * The [[http://guide.couchdb.org/draft/index.html|Definitive Guide]], which you can edit/fork/contribute to.
-  * The official [[https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs/s|source]], which will be in a {{{/docs}}} branch during integration Real Soon Now.
+  * The official [[https://git-wip-us.apache.org/repos/asf?p=couchdb.git;a=tree;f=share/docs;hb=docs|source]] now has a working {{{docs}}} branch
  
  We welcome your contributions to any of these - if you need help, just ask in IRC, or on the user email list. Thanks!
  
@@ -19, +19 @@

  
   * read the following tutorials and style guide
   * clone the [[https://git-wip-us.apache.org/repos/asf/couchdb.git|couchdb repository]]
-  * set up the python toolchain
+  * set up the python toolchain as below
-  * edit .rst files as needed in {{{share/sphinx-docs}}}
+  * edit .rst files as needed in {{{share/docs}}}
-  * build using {{{make html && make dirhtml && make singlehtml}}}
+  * build using this syntax in {{{share/docs}}}, replacing version, release, year as required
+ 
+ {{{
+ sphinx-build -a -E -W -n \
+ -D version='$ver' \
+ -D release='$ver-git-sha' \
+ -D project='Apache CouchDB' \
+ -D copyright='$year, Apache Software Foundation' \
+ -c `pwd` \
+ -d /tmp/ \
+ rst/ \
+ `pwd`/manual
+ }}}
+ 
   * check changes, make a patch & attach to a JIRA ticket, or send a pull request via github
  
  = RestructuredText and Sphinx Tutorials =
@@ -141, +154 @@

  done
  }}}
  
-  * To add a new chapter, simply add the new chapter inclusion into the manual {{{share/docs/manual/couchdb-manual.xml}}}
- 
- {{{
-     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="couchdb-new-chapter.xml"/>
- }}}
- 
- And then add a new chapter in the same folder the the above {{{href}}} as the filename. Here's a template, with the most common elements included:
- 
- {{{
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE section PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
-                          'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
- <!ENTITY % every.entities SYSTEM "entities.ent">
- %every.entities;
- ]>
- 
- <chapter id="couchdb-new-chapter">
- 
-   <title>dch is on your couch</title>
- 
-   <para>
-     Picture Time to get a new couch!!
-   </para>
- 
-   <para>
-     You know
-     <ulink url="http://www.erlang.org/">Erlang</ulink>
-    is delicious.
-   </para>
- 
-   <figure id="fig-couchdb-single-deathstar">
-    <title>deathstar fail</title>
- 
-       <mediaobject>
- 
-         <imageobject>
- 
-           <imagedata width="100%" contentdepth="100%" scalefit="1"
- fileref="images/deathstar_fail.png"
- format="PNG" lang="en"/>
- 
-         </imageobject>
- 
-         <textobject>
- 
-           <phrase lang="en">DeathStar Fail</phrase>
- 
-         </textobject>
- 
-       </mediaobject>
- 
-     </figure>
- 
-     <para>
-       This is a self-referential reference. Do not recurse without recourse!
-       <xref
-         linkend="couchdb-dch"/>.
-     </para>
- 
-     <para>
-       List out my good points!
-     </para>
- 
-     <itemizedlist>
-       <listitem>
-         <para>
-           I'm BIG in Germany.
-         </para>
- 
-       </listitem>
- 
-       <listitem>
-         <para>
-           RESTful is my nature
-         </para>
-       </listitem>
- 
-       <listitem>
-         <para>My temperament is Relaxed.</para>
-       </listitem>
- 
-     </itemizedlist>
- 
-     <table>
-       <title><literal>couchdb</literal> statistics</title>
-       <tgroup cols="3">
-         <colspec colname="stat"/>
-         <colspec colname="desc"/>
-         <colspec colname="unit"/>
-         <thead>
-           <row>
-             <entry>
-               Statistic ID
-             </entry>
-             <entry>
-               Description
-             </entry>
-             <entry>
-               Unit
-             </entry>
-           </row>
-         </thead>
-         <tbody>
-           <row>
-             <entry><literal>auth_cache_hits</literal>
-             </entry>
-             <entry>
-               Number of authentication cache hits
-             </entry>
-             <entry>
-               number
-             </entry>
-           </row>
-           <row>
-             <entry><literal>auth_cache_misses</literal>
-             </entry>
-             <entry>
-               Number of authentication cache misses
-             </entry>
-             <entry>
-               number
-             </entry>
-           </row>
-         </tbody>
-       </tgroup>
-     </table>
- 
- </chapter>
- }}}
- 
  = TODO =
  
   * TODO: ensure we have a documentation url for latest and each release on website