Sphinx docs

[Dirkjan Ochtman <di...@ochtman.nl>]

On Fri, Aug 3, 2012 at 4:00 PM, Noah Slater <ns...@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

Re: Sphinx docs

[Robert Newson <rn...@apache.org>]

+1

On 9 Aug 2012, at 01:23, Dave Cottlehuber 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 <ns...@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

Re: Sphinx docs

[Dave Cottlehuber <da...@muse.net.nz>]

On 13 August 2012 09:10, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Sunday, August 12, 2012, Dave Cottlehuber wrote:
>
>> Let me know if that's OK with y'all.
>>
>
> TBH I don't really like squashing (since I think having full small-chunk
> history is useful), but if that's the way CouchDB commits are done I guess
> it's fine.

Generally I'd agree, however the pre-squashed one was over 50 commits,
so for an initial import a cleanup is worth doing.

Thanks
Dave

Re: Sphinx docs

[Dirkjan Ochtman <di...@ochtman.nl>]

On Sunday, August 12, 2012, Dave Cottlehuber wrote:

> Let me know if that's OK with y'all.
>

TBH I don't really like squashing (since I think having full small-chunk
history is useful), but if that's the way CouchDB commits are done I guess
it's fine.

Stripping out the docbook tool chain sounds like a good idea.

Cheers,

Dirkjan

Re: Sphinx docs

[Dave Cottlehuber <da...@muse.net.nz>]

On 13 August 2012 00:48, Paul Davis <pa...@gmail.com> wrote:
> Looks pretty good. Only thing I see is if we shouldn't strip out the
> share/docs/DocKit directory on import. If we do that and reorder Jan's
> commit to after Dave's last commit we can get away without any import
> beyond the original XML sources.

Not sure what you intend with the reordering, but it makes sense to me to
have the XML commit first -- but rebase to exclude the helper scripts/tools.

> I'm mostly just concerned about how much data we're adding to the repo
> that will only exist for a few commits though it might also help us
> side step some legal issues if we just pull the CouchBase XML instead
> of all that code as well.

+1

A+
Dave

Re: Sphinx docs

[Robert Newson <rn...@apache.org>]

squashing is a noble art form that I strongly encourage. We don't need to see every minor tweak or mistake. The purpose of history is to inform.

B.

On 12 Aug 2012, at 23:48, Paul Davis wrote:

> Looks pretty good. Only thing I see is if we shouldn't strip out the
> share/docs/DocKit directory on import. If we do that and reorder Jan's
> commit to after Dave's last commit we can get away without any import
> beyond the original XML sources.
> 
> I'm mostly just concerned about how much data we're adding to the repo
> that will only exist for a few commits though it might also help us
> side step some legal issues if we just pull the CouchBase XML instead
> of all that code as well.
> 
> On Sun, Aug 12, 2012 at 7:05 AM, Noah Slater <ns...@tumbolia.org> wrote:
>> Woo, sounds good Dave. I'll wait for Paul, Bob, and Dirkjan to weigh in.
>> 
>> On Sun, Aug 12, 2012 at 8:39 AM, Dave Cottlehuber <da...@muse.net.nz> wrote:
>> 
>>> On 9 August 2012 17:35, Paul Davis <pa...@gmail.com> wrote:
>>>> 
>>>> 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
>>> 
>>> Paul, fine with me, I'll pick it up.
>>> 
>>> I rebased, squashed, merged & abused people's commits so now we have just
>>> 5:
>>> 
>>> https://github.com/dch/couchdb/commits/merge_docs
>>> 
>>> - Brian Mitchell - import CB docs
>>> - Jan  - hook up futon & makefiles
>>> - Dave - fix perl scripts for export
>>> - Dirkjan - turn into sphinx project, set up chapters
>>> - Alex Shorin - massive clean up
>>> - Dave - tweak a few things (JSON highlighting, set version to 1.3.x)
>>> 
>>> Let me know if that's OK with y'all.
>>> 
>>> A+
>>> Dave
>>> 
>> 
>> 
>> 
>> --
>> NS

Re: Sphinx docs

[Paul Davis <pa...@gmail.com>]

Looks pretty good. Only thing I see is if we shouldn't strip out the
share/docs/DocKit directory on import. If we do that and reorder Jan's
commit to after Dave's last commit we can get away without any import
beyond the original XML sources.

I'm mostly just concerned about how much data we're adding to the repo
that will only exist for a few commits though it might also help us
side step some legal issues if we just pull the CouchBase XML instead
of all that code as well.

On Sun, Aug 12, 2012 at 7:05 AM, Noah Slater <ns...@tumbolia.org> wrote:
> Woo, sounds good Dave. I'll wait for Paul, Bob, and Dirkjan to weigh in.
>
> On Sun, Aug 12, 2012 at 8:39 AM, Dave Cottlehuber <da...@muse.net.nz> wrote:
>
>> On 9 August 2012 17:35, Paul Davis <pa...@gmail.com> wrote:
>> >
>> > 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
>>
>> Paul, fine with me, I'll pick it up.
>>
>> I rebased, squashed, merged & abused people's commits so now we have just
>> 5:
>>
>> https://github.com/dch/couchdb/commits/merge_docs
>>
>> - Brian Mitchell - import CB docs
>> - Jan  - hook up futon & makefiles
>> - Dave - fix perl scripts for export
>> - Dirkjan - turn into sphinx project, set up chapters
>> - Alex Shorin - massive clean up
>> - Dave - tweak a few things (JSON highlighting, set version to 1.3.x)
>>
>> Let me know if that's OK with y'all.
>>
>> A+
>> Dave
>>
>
>
>
> --
> NS

Re: Sphinx docs

[Noah Slater <ns...@tumbolia.org>]

Woo, sounds good Dave. I'll wait for Paul, Bob, and Dirkjan to weigh in.

On Sun, Aug 12, 2012 at 8:39 AM, Dave Cottlehuber <da...@muse.net.nz> wrote:

> On 9 August 2012 17:35, Paul Davis <pa...@gmail.com> wrote:
> >
> > 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
>
> Paul, fine with me, I'll pick it up.
>
> I rebased, squashed, merged & abused people's commits so now we have just
> 5:
>
> https://github.com/dch/couchdb/commits/merge_docs
>
> - Brian Mitchell - import CB docs
> - Jan  - hook up futon & makefiles
> - Dave - fix perl scripts for export
> - Dirkjan - turn into sphinx project, set up chapters
> - Alex Shorin - massive clean up
> - Dave - tweak a few things (JSON highlighting, set version to 1.3.x)
>
> Let me know if that's OK with y'all.
>
> A+
> Dave
>



-- 
NS

Re: Sphinx docs

[Dave Cottlehuber <da...@muse.net.nz>]

On 9 August 2012 17:35, Paul Davis <pa...@gmail.com> wrote:
>
> 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

Paul, fine with me, I'll pick it up.

I rebased, squashed, merged & abused people's commits so now we have just 5:

https://github.com/dch/couchdb/commits/merge_docs

- Brian Mitchell - import CB docs
- Jan  - hook up futon & makefiles
- Dave - fix perl scripts for export
- Dirkjan - turn into sphinx project, set up chapters
- Alex Shorin - massive clean up
- Dave - tweak a few things (JSON highlighting, set version to 1.3.x)

Let me know if that's OK with y'all.

A+
Dave

Re: Sphinx docs

[Paul Davis <pa...@gmail.com>]

On Wed, Aug 8, 2012 at 7:23 PM, Dave Cottlehuber <da...@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 <ns...@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

Re: Sphinx docs

[Dave Cottlehuber <da...@muse.net.nz>]

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 <ns...@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

Re: Sphinx docs

[Hans J Schroeder <hs...@cloudno.de>]

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 <ns...@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

Re: Sphinx docs

[Noah Slater <ns...@tumbolia.org>]

Great thanks. I am also on vacation until Tuesday.



On 3 Aug 2012, at 18:01, Dirkjan Ochtman <di...@ochtman.nl> wrote:

> On Fri, Aug 3, 2012 at 4:00 PM, Noah Slater <ns...@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

Re: Sphinx docs

[Alexander Shorin <kx...@gmail.com>]

On Fri, Aug 3, 2012 at 9:53 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> At this point my repo is a straight descendant from dch's latest cset
> on the docs branch, so you can probably work from my branch on. (I
> used your conversion of the metadocs, BTW, thanks for that! I've
> credited you in the commit message.)

Oh, great! Glad that they was useful(: Ok, I'll checkout your branch
than and compare with what I had. Thanks!

--
,,,^..^,,,


On Fri, Aug 3, 2012 at 9:53 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Fri, Aug 3, 2012 at 7:35 PM, Alexander Shorin <kx...@gmail.com> wrote:
>> I'm ready to sent bucket of patches, but is your repo[1] be central
>> point to work on CouchDB sphinx docs?  Or it will be dch[2] one? In
>> other words, whom sent patches to prevent making same work twice? If
>> everyone will develop his own docs version there wouldn't be anything
>> good just only merge hell(:
>>
>> [1] https://github.com/djco/couchdb/tree/docs
>> [2] https://github.com/dch/couchdb/tree/docs
>
> At this point my repo is a straight descendant from dch's latest cset
> on the docs branch, so you can probably work from my branch on. (I
> used your conversion of the metadocs, BTW, thanks for that! I've
> credited you in the commit message.)
>
> Cheers,
>
> Dirkjan

Re: Sphinx docs

[Dirkjan Ochtman <di...@ochtman.nl>]

On Fri, Aug 3, 2012 at 7:35 PM, Alexander Shorin <kx...@gmail.com> wrote:
> I'm ready to sent bucket of patches, but is your repo[1] be central
> point to work on CouchDB sphinx docs?  Or it will be dch[2] one? In
> other words, whom sent patches to prevent making same work twice? If
> everyone will develop his own docs version there wouldn't be anything
> good just only merge hell(:
>
> [1] https://github.com/djco/couchdb/tree/docs
> [2] https://github.com/dch/couchdb/tree/docs

At this point my repo is a straight descendant from dch's latest cset
on the docs branch, so you can probably work from my branch on. (I
used your conversion of the metadocs, BTW, thanks for that! I've
credited you in the commit message.)

Cheers,

Dirkjan

Re: Sphinx docs

[Alexander Shorin <kx...@gmail.com>]

Hi Dirkjan,

I'm ready to sent bucket of patches, but is your repo[1] be central
point to work on CouchDB sphinx docs?  Or it will be dch[2] one? In
other words, whom sent patches to prevent making same work twice? If
everyone will develop his own docs version there wouldn't be anything
good just only merge hell(:

[1] https://github.com/djco/couchdb/tree/docs
[2] https://github.com/dch/couchdb/tree/docs

--
,,,^..^,,,


On Fri, Aug 3, 2012 at 9:01 PM, Dirkjan Ochtman <di...@ochtman.nl> wrote:
> On Fri, Aug 3, 2012 at 4:00 PM, Noah Slater <ns...@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