Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: pass (nike.apache.org: domain of djc.ochtman@gmail.com
 designates 74.125.82.180 as permitted sender)
MIME-Version: 1.0
Sender: djc.ochtman@gmail.com
From: Dirkjan Ochtman <dirkjan@ochtman.nl>
Date: Fri, 3 Aug 2012 19:01:56 +0200
Message-ID: 
 <CAKmKYaAa5eTLGdYZ533FytZAnUAKqDe3CdAiGZeoOxk-frLW3A@mail.gmail.com>
Subject: Sphinx docs
To: dev@couchdb.apache.org
Content-Type: text/plain; charset=UTF-8

On Fri, Aug 3, 2012 at 4:00 PM, Noah Slater <nslater@tumbolia.org> wrote:
> Dirkjan, please just concentrate on getting the output targets of your
> existing Makefile working. (The Makefile I saw when I checked out your
> Github repo last.) Don't bother yourself with Autotools. Just get the docs
> dir working as if it were a separate concern, and I will take care of
> integration.

Okay, I think this is done. You can still see the current result here:

http://couchdb.readthedocs.org/en/latest/index.html

I've tested the html and texinfo targets so far, both seem to be fine.
I've also left a TODO.txt for everyone who'd like to help out
improving the docs and just needs a little nudge in the right
direction.

I have not removed the DocBook-based docs yet, since they are used in
the build system and I didn't feel like messing with Noah's baby. ;)
(Also, listing each and every HTML file seems incredibly tedious.) You
can get the good stuff from https://github.com/djco/couchdb/tree/docs.
I'm not sure whether it should be merged to master first, then
included with the build system, or the other way around.

Basic workflow is this:

- Install docutils, pygments and sphinx via your system package
manager, easy_install or pip
- Go to share/sphinx-docs
- Edit any .rst files
- make html
- Lather, rinse, repeat

Helpful docs for those new to dealing with reST/Sphinx:

http://docutils.sourceforge.net/docs/user/rst/quickstart.html
http://sphinx.pocoo.org/rest.html

Also, I'm going on vacation for a bit. I'll be around a little bit
this weekend if there's anything you need from me, then I'll be gone
for a week without network.

Cheers,

Dirkjan