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] Update of "Documentation" by DaveCottlehuber
Date Thu, 09 Aug 2012 00:10:07 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=1&rev2=2

Comment:
include Wendall Cada's python env tips and Dirkjan Ochtman's Sphinx work!

  
   * The Wiki (you're here)
   * The [[http://guide.couchdb.org/draft/index.html|Definitive Guide]]
-  * The source tree, which is [[https://github.com/dch/couchdb/tree/docs/share/docs|under
work]]
+  * The source tree, which will live in during [[https://github.com/apache/couchdb/tree/docs/share/docs|integration]]
  
- = Editing Documentation =
+ == Editing the Docs ==
  
- == DocBook Style ==
+ === RestructuredText and Sphinx Tutorials ===
  
+ There are plenty of helpful tutorials out there:
+ 
+  * The [[http://sphinx.pocoo.org/rest.html| Sphinx site]] has a great introduction
+  * The official [[http://docutils.sourceforge.net/docs/user/rst/quickstart.html|quick start
guide]]
+  * 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 either directly in github
or on your computer, and then send a pull request.
+ 
+ == 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.
+ 
+ === 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:
+ 
+ {{{
+ cd $MY_COUCH_SOURCE_REPO
+ virtualenv env
+ source env/bin/activate
+ which python pip
+ 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.
+ 
+ === Generation via Makefile ===
+ 
+  * Load the python/sphinx environment
+ 
+ {{{
+ cd $MY_COUCH_SOURCE_REPO
+ source ./env/bin/activate
+ cd share/docs/sphinx-docs
+ }}}
+ 
+  * Ensure that you don't have any other pending doc changes by running {{{make changed}}}.
Output should be similar to this:
+ {{{
+ sphinx-build -b changes -d build/doctrees   . build/changes
+ Making output directory...
+ Running Sphinx v1.1.3
+ loading pickled environment... not yet created
+ building [changes]: /Users/dch/repos/couch/git/share/sphinx-docs/build/changes
+ updating environment: 25 added, 0 changed, 0 removed
+ reading sources... [100%] views
+ looking for now-outdated files... none found
+ pickling environment... done
+ checking consistency... done
+ no changes in version 1.3.x.
+ build succeeded.
+ }}}
+ 
+  * 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:
+ 
+ {{{
+ mkdir _static
+ make html && make dirhtml && make singlehtml
+ }}}
+ 
+ TODO: should be some checks here
+ 
+  * Import the generated documentation into CouchDB source tree
+ 
+ TODO: again, this should be part of main Makefile
+ 
+ === 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.
+ 
- To add a new chapter, simply add the new chapter inclusion into the manual {{{share/docs/manual/couchdb-manual.xml}}}
+  * 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"/>

Mime
View raw message