Dear wiki user, You have subscribed to a wiki page "Couchdb Wiki" for change notification.
The page "Documentation" has been deleted by JoanTouzet: https://wiki.apache.org/couchdb/Documentation?action=diff&rev1=28&rev2=29 Comment: This is all long-since done. - <<Include(EditTheWiki)>> <<TableOfContents(3)>> - 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 is currently still a bit scattered, however, authoritative documentation is now in the repo and available for browsing online. Unfortunately, some things are still documented only here on this wiki or in mailinglist posts/commit messages/github gists/etc. but should be in the official documentation; contributions welcome. - - * The [[http://docs.couchdb.org/|Official Documentation]] - * 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;hb=docs|source]] now has a working {{{docs}}} branch - * The ASF [[https://github.com/apache/couchdb/tree/docs|github mirror]] now has a working {{{docs}}} branch too - get forking! - * A [[http://couchdb.readthedocs.org/|searchable HTML page]] and packaged [[https://readthedocs.org/projects/couchdb/downloads/|downloads]] are generated using the awesome Read The Docs site. - - 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 as below - * edit .rst files as needed in {{{share/doc}}} - * build using this command in {{{share/doc}}}, replacing version, release, year as required, to generate separate HTML pages per chapter: - - {{{ - 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 - }}} - - * this variant produces a single HTML page for the 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 - }}} - - * check changes, make a patch & attach to a JIRA ticket, or send a pull request via github - - = 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: - - * 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 - - == Adding Version Added/Changed or Deprecated Information == - - Sphinx supports [[http://sphinx.pocoo.org/markup/para.html#directive-versionadded|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 = - - [[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 == - - Before editing the documentation, get your own editable copy of the repository, and choose the most appropriate branch to work on: - - {{attachment:github_fork_and_select_branch.png}} - - 1. Fork: as you will not have write permission to the ASF CouchDB git mirror, you'll need to make your own fork, or copy. Just click on the {{{fork}}} button, and you're done. - 1. 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. - 1. 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 == - - Now that you've got a suitable branch selected: - - * Browse into {{{share/docs/rst}}} - * Identify the file you want to edit/alter. - - {{attachment:github_rst_formatted_view.png}} - - * Switch to raw view and start editing! Note that you can switch back between source and edit view without losing your content. - - {{attachment:github_rst_raw_view.png}} - - * Once you're happy with the changes, add a suitable brief commit message, prefaced with {{{docs:}}} - - {{attachment:github_rst_commit_msg.png}} - - * 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: - - {{{ - 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 [[http://www.tug.org/mactex/2009/|MacTex]] for this. - - ''Can someone explain why a virtual environment is needed? Why can't, or shouldn't, I just install these packages normally? ~ Noah S.'' - - ''Virtualenv is good common practice to not mix system wide installed Python packages with project required ones. While in most cases you will not face any problems with installing sphinx and all his dependencies system wide, there are some edge cases that could make things broken: - - - Your system package manager doesn't have sphinx or some of his depended package available to install. Manual system wide installation is like `make && make install` - one more step closer to unmanaged system; - - - You already has sphinx installed, but of version that has breaking changes against required one, and you're needed this different version - updating could break something for you; - - Since Python 3.3 release there wouldn't be any requirement for virtualenv since it goes to be in [[http://docs.python.org/dev/library/venv.html#module-venv|stdlib]] and sphinx is ready for Python 3.x. ~ Alexander Sh. - '' - - == Generation via ReadTheDocs == - - To regenerate [[http://couchdb.readthedocs.org/|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 [[https://readthedocs.org/builds/couchdb/|build progress]] and also grab the various built [[https://readthedocs.org/projects/couchdb/downloads/|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 [[http://couchdb-dev.readthedocs.org|results]] directly, or see the [[https://readthedocs.org/dashboard/couchdb-dev/|error log]]. You will be added as a contributor to it on your first pull request. - - = ToDos = - - Check out the [[https://issues.apache.org/jira/browse/COUCHDB/component/12312239|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 [[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 - }}} -
