Mailing-List: contact dev-help@couchdb.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@couchdb.apache.org
Received-SPF: pass (athena.apache.org: domain of djc.ochtman@gmail.com
 designates 74.125.82.54 as permitted sender)
MIME-Version: 1.0
Sender: djc.ochtman@gmail.com
In-Reply-To: 
 <CA+Y+447V5pZ3kDOZr3GeNRL6_0WEQSq1QKHpG_wVoHrAsbDtAQ@mail.gmail.com>
References: <EC73BB16-F86A-4F6B-9143-A22B88381108@apache.org>
 <8A69B3F1-C955-4127-B92B-B0DA1AA9AEB6@apache.org>
 <19EB8367-1282-4406-9C51-B3AE4AFA0080@apache.org>
 <D5FEC7AA-2294-41F5-81E9-AF982BF29976@apache.org>
 <2E5C3210-58B9-48A7-9E21-3B6206D24899@apache.org>
 <382956416E9B4787895A95D59AC5ECC1@cloudant.com>
 <70658AB3-81FA-4E3A-ABE6-D6299ED2704A@apache.org>
 <E2D5A5F1B3794024BBEC5AD03852711F@cloudant.com>
 <436CC93B-6244-4A01-9933-46B2937AB331@apache.org>
 <FF69394627DB40C0BFE9CBC7AE253631@cloudant.com>
 <872CBFC9-B758-492C-8297-410600E6DA84@tumbolia.org>
 <BD8ECF010F6E41C4A5F69DA433E09A6C@cloudant.com>
 <CAHZBNKb-+V6qn=eNnmKyLTZfh32QvFj=CnY_JPHdm3s--dBzLw@mail.gmail.com>
 <CAJNb-9rMGryj13gLJXqcmirc-6kRjNjT9YocCmyFmfcuipO4OQ@mail.gmail.com>
 <15663FC5-C39A-480E-90F3-DE29A90B51CC@apache.org>
 <CAJNb-9ozBHXK8t9neyr-K=9dQA9TvKPQpyX5Lp0Ss4Sqq_8mWA@mail.gmail.com>
 <141BD7F5-CCBB-4DFA-A8D7-8D0E58A9FCB4@apache.org>
 <CAKmKYaC_8nuahD4q=DAUC5BTJ58iCsiwfh+CBMB6ZcnGHTX1RQ@mail.gmail.com>
 <29AACC7D6BF74C14BC1AB920E643AA56@cloudant.com>
 <CAKmKYaBoazt-OCeLgR6q9GUka8SJcKiV4Ego7Nxx7Knp+EhE0g@mail.gmail.com>
 <CAJNb-9p6n67-UuEKxB4mbFo22X3ckF=FWtYGhCqXowgZAwmPMQ@mail.gmail.com>
 <6B233E41-1CC5-49A1-966D-DC2912D6CC8B@tumbolia.org>
 <CAJNb-9o8nHt0OqmZvH4A+sAxNSqkR3COH7ugTMw0_LQ=65wO2A@mail.gmail.com>
 <CA+Y+446th8T---VWZWc21yei=M_cKf0bU51tiNAkra+RXa5MEQ@mail.gmail.com>
 <CAHZBNKY8TLYZsmFpRYeuZGhaZS7yR1T5fu3WNRmVt55+V8sKNw@mail.gmail.com>
 <CAKmKYaAjOHZaNezQoWoJ_qPFbPB673unBnZELRnegdQDkkiygA@mail.gmail.com>
 <CA+Y+447V5pZ3kDOZr3GeNRL6_0WEQSq1QKHpG_wVoHrAsbDtAQ@mail.gmail.com>
From: Dirkjan Ochtman <dirkjan@ochtman.nl>
Date: Wed, 1 Aug 2012 14:07:05 +0200
Message-ID: 
 <CAKmKYaC--rxBa7=z957LiM=eP7=KG9h0uyjKyUweH__P4m1Y1g@mail.gmail.com>
Subject: Re: Docs, second try
To: dev@couchdb.apache.org
Content-Type: text/plain; charset=UTF-8

On Wed, Aug 1, 2012 at 2:00 PM, Noah Slater <nslater@tumbolia.org> wrote:
> What is Pytohn nirvana? Is that related to the Sphinx effort I checked out
> towards the end of this thread?

Sphinx is written in Python, but I'm not sure why Dave mentioned the
Python nirvana. You don't need to write any Python to improve Sphinx
docs, just installing some Python-based tools to turn them into HTML
or any of other output formats.

> I think once the docs are converted to RST and the Sphinx work looks okay,
> we should merge this into master, and I am offering to take over from
> there. I will happily integrate this into the build system, hook it up with
> Futon, update the README files, etc.
>
> What is standing between here and there?
>
> What is there left to do before we can get the Sphinx work into master for
> further iteration?

The conversion from DocBook to Sphinx isn't perfect, so it needs a bit
of tweaking to fix up links and some minor syntax issues. I'm happy to
work on that; I think it makes sense to keep this work on the docs
branch for a bit longer while these small issues get fixed.

I'm also happy to do further work after that (though I may not be the
best person to work on autotools integration, other than calling the
Sphinx Makefile from one of the other Makefiles).

Cheers,

Dirkjan

>
> On Wed, Aug 1, 2012 at 12:28 PM, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:
>
>> On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <dave@muse.net.nz> wrote:
>> > Do we have a concensus now to go for RST & python nirvana?
>>
>> If we do, a proposed plan forward, with Dave and Robert N.:
>>
>> - Keep the docs branch as it is, with DocBook docs
>> - Iterate on the Sphinx docs in the docs branch (for example based on my
>> csets)
>> - When everything has properly been converted to Sphinx, remove DocBook
>> files
>> - At this point, merge docs into master and do further improvement
>>
>> This means the DocBook version is safely in repository history for
>> archival purposes. Sphinx building can easily be integrated into
>> Makefiles, we'll also need to update some READMEs etc to document
>> Sphinx dependencies. We should probably not wait until the docs are
>> perfect before merging into master, but make sure everything from the
>> DocBook version is in there.
>>
>> I'll note that I think the pace of movement around the Sphinx stuff
>> indicates that this significantly helps contribution to the docs, so I
>> think this would be a great way to move forward.
>>
>> Cheers,
>>
>> Dirkjan
>>
>
>
>
> --
> NS