Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Info
titleBecome a contributor

You need to be added as a contributor to edit the wiki. But don't worry! Just email any Mailing List or grab us on IRC and let us know your user name.

 

...

Introduction to CouchDB Documentation

Contributing to the CouchDB Documentation is one of the most valuable things you can do - every bit helps.  This document will also guide you on how you can contribute.
  CouchDB Documentation is bit scattered, however, authoritative documentation is now in the git repository and available for browsing on-line. Unfortunately, some things are still available only on this wiki or in mailing lists/commit messages/github gists/etc, which ideally should have been in the official documentation; contributions are welcome and greatly appreciated.   

...

We welcome your contributions to any of these - if you need help, just ask in IRC, or on the dev email list. Thanks!! 

The Quick Start Guide

...

  • Read the sphinx tutorials and style guide (pointers below). 
  • Clone the couchdb repository

  • Set up the python tool-chain as described below.

  • Edit .rst files as needed in share/doc

  • Build using this command in share/doc, replacing version, release, year as required, to generate HTML pages(select a command based on per page HTML or single HTML),

    Code Block
    themeMidnight
    languagebash
    titleCommand - Separate HTML per page
    sphinx-build -a -E -W -n -b html \
    -D version='$ver' \
    -D release='$ver-git-sha' \
    -D project='Apache CouchDB' \
    -D copyright='$year, Apache Software Foundation' \
    -d $TMPDIR/couchdocs/ \
    src/ \
    `pwd`/manual
    Code Block
    themeEmacs
    languagebash
    titleCommand - Single HTML for whole docs
    sphinx-build -a -E -W -n -b singlehtml \
    -D version='$ver' \
    -D release='$ver-git-sha' \
    -D project='Apache CouchDB' \
    -D copyright='$year, Apache Software Foundation' \
    -d $TMPDIR/couchdocs/ \
    src/ \
    `pwd`/manual
  • Double check all the changes, make a patch & attach to a JIRA ticket, or send a pull request via github. 

  • Whew! Congratulations, you are contributing now.

Restructured Text(.rst) 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 online eventually.

...

There are plenty of helpful tutorials out there:   

Adding Version Added/Changed or Deprecated Information

...

Sphinx supports paragraph-level annotations for tracking when functionality was modified. By adding this information directly to the .rst documentation during committing any functionality, future NEWS and CHANGES updates can be directly extracted from Sphinx. 

Editing Documentation via GitHub 

GitHub supports displaying .rst files with correct formatting directly in their web UI. This makes quick updates very easy, using the mirrored ASF CouchDB documentation git repository.   

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:   

...

 

...


  1. Fork: as you will not have write permission to the ASF CouchDB-documentation git mirror, you'll need to make your own fork, or copy. Just click on the fork button, and you're done.   

  2. Branch if needed: Once you have your own fork, list the available branches from the drop-down menu. The /docs branch will be used to build 1.3.0 release.  

  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.   

...

  1. If you are stuck with identifying the correct branch etc, drop an email to dev@couchdb.apache.org or catch folks on IRC (#couchdb-dev).

Driving GitHub UI

Now that you've got a suitable branch selected:   

 

  • Browse
  • into share/docs/rst  
  • to the required rst file.
  • Identify the file you want to edit/alter
  • .   

...

  • and click on edit button on github menu.   
  • Switch to raw view and start editing! Note that you can switch back between source and edit view without losing your content.  
  •  

github_rst_raw_view.pngImage Removed   

  • Once you're happy with the changes, add a suitable brief commit message
  • , prefaced with docs:   

github_rst_commit_msg.pngImage Removed   

  • and follow the contributor guide to send your patch for developer code review. 
  • Once done,
  • Send a pull request and
  • the committers will pick up your documentation changes, and your Karma will be increased!    

 

Generating Docs

  

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

...

Assuming you have python 2.7 or a close relative, the following instructions will set up a python virtual environment containing the required tools:   

 

...

Code Block
themeEmacs
languagebash
titleSetting up Python and Sphinx-build
$~> cd $MY_COUCH_SOURCE_REPO  

...

$~> virtualenv env  

...

$~> source env/bin/activate  

...

$~> which python pip  

...

$~> pip install sphinx docutils pygments

  

In future, you'll only need to run source $MY_COUCH_SOURCE_REPO/env/bin/activate in each shell / prompt you run in.     

If you want to build the PDF, info files, etc, you will need a working TeX installation. Mac OS X users can use MacTex for this.   

...

Since Python 3.3 release there wouldn't be any requirement for virtualenv since it goes to be in stdlib and sphinx is ready for Python 3.x. ~ Alexander Sh.     

 

Generation via ReadTheDocs

...

 

To regenerate the online docs, push your changes to the /docs branch, and then POST to a build-specific URL curl -vX POST http://readthedocs.org/build/4251. You can track the build progress and also grab the various built formats.   

The https://github.com/dch/couchdb/tree/docs repo has a github post-commit hook already set up, so for testing you can use that repo, and view your results directly, or see the error log. You will be added as a contributor to it on your first pull request.    

 

ToDos

  

Check out the documentation component in JIRA for our current TODO list.   

@@ Replace this with a shared filter, once you have permissions. ~ Noah S.   

 

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 that the world was much harder in days gone by.   

The DocBook source was exported using pandoc which is available as a binary on most common platforms, as follows:   

...


 

...

Code Block
themeEmacs
languagebash
titleUsing pandoc
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