couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Trivial Update of "Documentation" by DaveCottlehuber
Date Thu, 09 Aug 2012 09:25:56 GMT
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=4&rev2=5

  <<Include(EditTheWiki)>>
- <<TableOfContents(2)>>
+ <<TableOfContents(3)>>
  
- Contributing Documentation to the CouchDB project is one of the most valuable things you
can do. Every bit helps. Here's how.
+ Contributing Documentation to the CouchDB project is one of the most valuable things you
can do - every bit helps. Here's how.
  
  = Take me to your Docs =
  
- Documentation can be found in 3 places today;
+ Documentation can be found in a number of places today;
  
-  * The Wiki (you're here)
+  * The [[https://wiki.apache.org/couchdb/|CouchDB Wiki]] (you're here)
-  * The [[http://guide.couchdb.org/draft/index.html|Definitive Guide]]
+  * The [[http://guide.couchdb.org/draft/index.html|Definitive Guide]], which you can edit/fork/contribute
to.
-  * The source tree, which will live in during [[https://github.com/apache/couchdb/tree/docs/share/docs|integration]]
+  * 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.
  
- == Editing the Docs ==
+ We welcome your contributions to any of these - if you need help, just ask in IRC, or on
the user email list. Thanks!
  
+ = The Quick Start Guide =
+ 
+  * 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
+  * edit .rst files as needed in {{{share/docs/sphinx-docs}}}
+  * build using {{{make html && make dirhtml && make singlehtml}}}
+  * check changes, make a patch & attach to a JIRA ticket, or send a pull request via
github
+ 
- === RestructuredText and Sphinx Tutorials ===
+ = RestructuredText and Sphinx Tutorials =
+ 
+ The official source contains {{{.rst}}} (Restructured Text) files used for API and release
notes. These will be published with every CouchDB release, and made available [[http://couchdb.apache.org/docs|online]]
eventually.
  
  There are plenty of helpful tutorials out there:
  
@@ -24, +35 @@

   * A [[http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html|cheatsheet]] for both
Sphinx and rst
   * If you want to regenerate the documentation into HTML, the [[http://sphinx.pocoo.org/index.html|Sphinx]]
guide may be of interest
  
- TODO: describe how to fork a suitable repo, edit the .rst file on your computer, and then
send a pull request.
- 
- === Editing Documentation via GitHub ===
+ = Editing Documentation via GitHub =
  
  [[https://github.com|GitHub]] supports displaying .rst files with correct formatting directly
in their web UI. This makes quick updates very easy, using the mirrored ASF [[https://github.com/apache/couchdb|CouchDB
git repository]].
  
- ==== Get your own Fork ====
+ == Get your own Fork ==
  
  Before editing the documentation, get your own editable copy of the repository, and choose
the most appropriate branch to work on:
  
@@ -40, +49 @@

   2. Branch if needed: Once you have your own fork, list the available branches from the
drop-down menu.
   3. The correct branch will depend a lot on where things are in the release cycle. In most
cases, you'll simply want to pick either the patch branch for the last release (e.g. the 1.2.0
release will have a corresponding 1.2.x branch, as shown above), or more often, use the current
{{{master}}} branch which will eventually be used to generate the next major release. For
example, after 1.2.0, would come 1.3.0.
  
+ == Driving GitHub UI ==
- TODO: ensure we have a documentation url for latest and each release on website
- 
- ==== Editing inside GitHub ====
  
  Now that you've got a suitable branch selected
  
@@ -61, +68 @@

  
   * Send a pull request and the committers will pick up your documentation changes, and your
Karma will be increased!
  
- == Generating Docs ==
+ = Generating Docs =
  
- This should be done for each pull request to ensure the formatting and linking in particular
is still correct, prior to commit or merge.
+ Documentation should be freshly generated for each pull request, to ensure the formatting
and linking in particular is still correct, prior to commit or merge.
  
- === Setting up Python and Sphinx for the first time ===
+ == Setting up Python and Sphinx for the first time ==
  
  Assuming you have python 2.7 or a close relative, the following instructions will set up
a python virtual environment containing the required tools:
  
@@ -77, +84 @@

  pip install sphinx docutils pygments
  }}}
  
- In future, you'll need to run {{{source $MY_COUCH_SOURCE_REPO/env/bin/activate}}} in each
shell / prompt you run in.
+ In future, you'll only need to run {{{source $MY_COUCH_SOURCE_REPO/env/bin/activate}}} in
each shell / prompt you run in.
  
- === Generation via Makefile ===
+ == Generation via Makefile ==
  
   * Load the python/sphinx environment
  
@@ -107, +114 @@

  
   * Update copyright, release and version fields in {{{/share/docs/sphinx-docs/conf.py}}}
  
- TODO: include version and release updates into main Makefile
- 
   * Generate targets via:
  
  {{{
@@ -120, +125 @@

  
   * Import the generated documentation into CouchDB source tree
  
- TODO: again, this should be part of main Makefile
+ = Quick Guide to DocBook =
  
- === Adding a Chapter ===
- 
- = DocBook =
- 
- The original Couchbase-provided API documentation came in DocBook form. XML is feared and
loathed by the Couch Community, who prefer to Relax with JSON. Much wailing and gnashing of
teeth was done, and eventually the foul beast was slain by a thousand IRC cuts and ten thousand
reply-to-alls. Those who have no fear may find the following lightweight information of use.
Others may use it to scare small children and remind teenagers how the world was much harder
in days gone by.
+ The original Couchbase-provided API documentation came in DocBook form. XML is feared and
loathed by the Couch Community, who prefer to Relax with JSON. Much wailing and gnashing of
teeth was done, and eventually the foul beast was slain by a thousand IRC cuts and ten thousand
reply-to-alls. Those who have no fear may find the following lightweight information of use.
Others may use it to scare small children and remind teenagers that the world was much harder
in days gone by.
+ 
+ The DocBook source was exported using [[http://johnmacfarlane.net/pandoc/|pandoc]] which
is available as a binary on most common platforms, as follows:
+ 
+ {{{
+ for xml in *.xml; \
+ do echo ${xml}; \
+ pandoc
+     --smart --preserve-tabs --normalize --reference-links --chapters \
+     --number-sections --standalone --from docbook --to rst \
+     --output ../dist/${xml} ${xml};
+ done
+ }}}
  
   * To add a new chapter, simply add the new chapter inclusion into the manual {{{share/docs/manual/couchdb-manual.xml}}}
  
@@ -258, +271 @@

  </chapter>
  }}}
  
+ = TODO =
+ 
+  * TODO: ensure we have a documentation url for latest and each release on website
+  * TODO: missing the section about actually get docs cloned to your computer
+  * TODO: missing how to add chapters, minimal .rst cutnpaste examples, inter-doc references
+  * TODO: sort out core makefile changes
+  * TODO: how to distribute updates to CouchDB core website?
+  * TODO: again, this should be part of main Makefile
+  * TODO: update copyright, version and release updates from core Makefile
+ 

Mime
View raw message