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 kxepal@gmail.com designates
 74.125.83.52 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <6B233E41-1CC5-49A1-966D-DC2912D6CC8B@tumbolia.org>
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>
Date: Wed, 1 Aug 2012 06:11:55 +0400
Message-ID: 
 <CAHdjipKkfjyamQwXV0UMnjZb6g7MT8DEAzU33Bky0wxoM_iDMA@mail.gmail.com>
Subject: Re: Docs, second try
From: Alexander Shorin <kxepal@gmail.com>
To: dev@couchdb.apache.org
Content-Type: text/plain; charset=UTF-8

Hi all!

I had some free time to try port docbook docs to sphinx and that's
what I'd done:

http://kxepal.iriscouch.com/docs/1.1/index.html

Currently I'd done 1-9 chapters, some typo fixes and little structure
refactoring and now I have to go work. Others things + term generation
I could try to finish later during lunch at work, if nobody minds.

sources with repo and prebuilded html files if someone needed:
http://kxepal.iriscouch.com/docs/1.1/couchdb-docs.zip

Hope this helps somehow(:

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


On Wed, Aug 1, 2012 at 5:52 AM, Noah Slater <nslater@tumbolia.org> wrote:
> Sorry guys. Life got in the way, as it does.
>
> As I see it, we have two options:
>
> 1) Pick a source format that can convert to Texinfo. The source format should be easy to EDIT. The Texinfo requirement is so that it hooks in to Autotools. (Which gives us info pages, HTML, PDF, etc, for free.)
>
> 2) Write the docs in HTML.
>
> Has anyone considered option 2?
>
> If you don't think it's possible, or would be complex to edit, see:
>
> https://github.com/oreilly/couchdb-guide/
>
> The only downside to option 2 is that we will have to develop a style guide, and enforce it, if we wish to keep the source clean and readable. (Again, see above.)
>
> I have lots of DocBook experience, and I am still prepared to run point on this. (If you will forgive my previous lack of attention.)
>
> If we can build consensus around which option we want to go with, I can allocate some time upfront to getting the existing stuff imported, converted, and in a state ready to ship.
>
>
>
> On 31 Jul 2012, at 22:22, Benoit Chesneau <bchesneau@gmail.com> wrote:
>
>> On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <dirkjan@ochtman.nl> wrote:
>>> I've converted the docs into reST + Sphinx here (via Pandoc):
>>>
>>> https://github.com/djco/couchdb/tree/docs/share/docs/sphinx-docs
>>> http://couchdb.readthedocs.org/en/latest/
>>>
>>> This needs a little more reordering and structuring, but I think it
>>> looks pretty good already.
>>>
>>> I'd be happy to work on this more so it'll be a good resource before
>>> the next release.
>>>
>>> Cheers,
>>>
>>> Dirkjan
>>
>> That's awesome. I like it :) Thanks!
>>
>> I guess we could try some custom module later on a second pass, like this one :
>>
>> http://packages.python.org/sphinxcontrib-httpdomain/
>>
>> But current result is enough by itself. I guess we could reuse the
>> makefile provided with sphinx and integrate it in our sources too.
>> Then last piece of work is adding a custom --generate-doc option to
>> autotools :)
>>
>> - benoit