couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Cottlehuber <d...@muse.net.nz>
Subject Re: Sphinx docs
Date Thu, 09 Aug 2012 00:23:08 GMT
On 4 August 2012 11:25, Hans J Schroeder <hs@cloudno.de> wrote:
> This is great, thanks.
>
> For those building on Mac OS X:
>
> When "make html" stops with: ValueError: unknown locale: UTF-8
>
> set the following env vars:
>
> export LANG=en_US.UTF-8
> export LC_ALL=en_US.UTF-8
>
> - Hans
>
> On Aug 3, 2012, at 7:01 PM, Dirkjan Ochtman wrote:
>
>> 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
>

I am *so* stoked to see this moving! I've started documenting how to
edit/generate the docs http://wiki.apache.org/couchdb/Documentation -
thanks Wendall for python assistance.

Can anybody confirm if the python steps work on linux?

Next:
- squash patches
- confirm this all works nice on github for in-page editing & document that
- finish proof reading

Unless there's any objections from PMC, I'd like to push the original
CB xml + Dirkjan's Sphinx Sauce into a new /docs branch based off
current master.

A+
Dave

Mime
View raw message