incubator-couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paul Davis <paul.joseph.da...@gmail.com>
Subject Re: Sphinx docs
Date Thu, 09 Aug 2012 15:35:16 GMT
On Wed, Aug 8, 2012 at 7:23 PM, Dave Cottlehuber <dave@muse.net.nz> wrote:
> 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

Dave,

I'd like to cross the i's and dot the t's on the legal bits here. The
only stuff I can find on CC licenses is at [1] which talks about
unmodified and mentions that we may need the appropriate README/NOTICE
updates. We may also want to look at the size of the contribution and
maybe get a code grant thinger (again, docs vs code, no idea on
precedent).

Let me know if you want to head up that discussion or if I should
start a thread for it.

[1] http://www.apache.org/legal/resolved.html#cc-sa

Mime
View raw message