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 Wed, 26 Sep 2012 21:41:12 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=11&rev2=12

Comment:
add RTD info

+ <<Include(EditTheWiki)>> <<TableOfContents(3)>>
- <<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.
  
@@ -13, +12 @@

   * 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!
  
@@ -22, +22 @@

   * 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/docs}}}
-  * build using this syntax in {{{share/docs}}}, replacing version, release, year as required
+  * build using this command in {{{share/docs}}}, replacing version, release, year as required
  
  {{{
  sphinx-build -a -E -W -n \
@@ -34, +34 @@

  rst/ \
  `pwd`/manual
  }}}
- 
   * check changes, make a patch & attach to a JIRA ticket, or send a pull request via
github
  
  = RestructuredText and Sphinx Tutorials =
@@ -43, +42 @@

  
  There are plenty of helpful tutorials out there:
  
-  * The [[http://sphinx.pocoo.org/rest.html| Sphinx site]] has a great introduction
+  * 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
@@ -59, +58 @@

  {{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.
-  2. Branch if needed: Once you have your own fork, list the available branches from the
drop-down menu.
+  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.
-  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. 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
+ Now that you've got a suitable branch selected:
  
   * Browse into {{{share/docs/rst}}}
   * Identify the file you want to edit/alter.
@@ -75, +74 @@

  
  {{attachment:github_rst_raw_view.png}}
  
-  * Once you're happy with the changes, add a suitable brief commit message:
+  * Once you're happy with the changes, add a suitable brief commit message, prefaced with
{{{docs:}}}
  
  {{attachment:github_rst_commit_msg.png}}
  
@@ -86, +85 @@

  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:
  
  {{{
@@ -96, +94 @@

  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.
  
  == Generation via Makefile ==
  
-  * Load the python/sphinx environment
+ There is no makefile support yet. It should do the following:
  
- {{{
- cd $MY_COUCH_SOURCE_REPO
- source ./env/bin/activate
- cd share/docs
- }}}
+  * check sphinx-build is in path
+  * output temporary files outside the build chain using the {{{-d $TMPDIR/somewhere}}} option
+  * output final files into the directory provided as last parameter, currently {{{`pwd`/manual}}}
+  * update release, year, version, as required in the sphinx-build call
+  * handle VPATH correctly
+  * output the HTML documentation into the right place for generating the release tar.gz
artefacts
+  * ensure the futon link does the right thing
  
+ == Generation via ReadTheDocs ==
-  * 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/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/rst/conf.py}}}
+ 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]].
  
-  * Generate targets via:
+ The [[https://github.com/dch/couchdb/tree/docs]] repo has a hidden post-commit hook set
up so for testing you can use that and view your results directly. You will be added as a
contributor to it on your first pull request.
  
+ = ToDos =
- {{{
- mkdir _static
- make html && make dirhtml && make singlehtml
- }}}
  
- TODO: should be some checks here
+  * ensure we have a documentation url for latest and each release on website
+  * missing how to add chapters, minimal .rst cutnpaste examples, inter-doc references
+  * sort out core makefile changes
+  * how to distribute updates to CouchDB core website?
  
+ = DocBook =
-  * Import the generated documentation into CouchDB source tree
- 
- == DocBook export ==
  
  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.
  
@@ -154, +137 @@

  done
  }}}
  
- = 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
-  * TODO: get http://readthedocs.org/ and the ASF docs branch playing nicely
- 

Mime
View raw message