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 robert.newson@gmail.com
 designates 74.125.82.180 as permitted sender)
Content-Type: text/plain; charset=iso-8859-1
Mime-Version: 1.0 (Apple Message framework v1278)
Subject: Re: Docs, second try
From: Robert Newson <robert.newson@gmail.com>
In-Reply-To: 
 <CAJNb-9o7nKtt0uSVYkvZUYTGRKYpXTBM-yaKabD1=hHDFswQqg@mail.gmail.com>
Date: Fri, 3 Aug 2012 12:50:21 +0100
Content-Transfer-Encoding: quoted-printable
Message-Id: <112A59E2-200B-44B8-9C58-E75F550649B9@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>
 <29AACC7D6BF74C1
 4BC1AB920E643AA56@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>
 <CAKmKYaC--rxBa7=z957LiM=eP7=KG9h0uyjKyUweH__P4m1Y1g@mail.gmail.com>
 <CA+Y+446wp0iPapzx5hEkFzcVd6ENb9mZpWWR2rTXMcGX7XhsPg@mail.gmail.com>
 <CAJNb-9o7nKtt0uSVYkvZUYTGRKYpXTBM-yaKabD1=hHDFswQqg@mail.gmail.com>
To: dev@couchdb.apache.org


The docs should be hosted on https://couchdb.apache.org/ imo.

B.

On 3 Aug 2012, at 04:47, Benoit Chesneau wrote:

> On Wed, Aug 1, 2012 at 2:21 PM, Noah Slater <nslater@tumbolia.org> =
wrote:
>> That's fine. Just get the Sphinx makefile working enough to generate =
the
>> docs in the current working directory. Then merge your docs branch to
>> master. At that point, I will convert your makefile into an Autotools
>> makefile, and hook it up with all the right stuff. Sounds like we =
have
>> consensus, and a tag-team plan. :D
>=20
>=20
> I'm trying to summarize the actions we need to put in place here:
>=20
> 1. create the doc branch , start to track the process of the
> conversion to make sure we didn't lost an information.
> 2. hack the autotools to handle this makefile and the needed check
> 3. hoock it to git? (can we do that actually on the apache website)
>=20
> Where do we host the doc?
>=20
> - Do we need to host it on the apache website? Which would imply to
> hack the site generation to make sure the generated docs are landing
> in a folder.
> - Do we hosts them on readthedocs under docs.couchdb.org ?
> - both
>=20
> Where do we place the donated docs?. Some where speaking to post them
> in a branch, zhich is good imo. But did the donation follow the apache
> process for that?
>=20
> - benoit
>>=20
>> On Wed, Aug 1, 2012 at 1:07 PM, Dirkjan Ochtman <dirkjan@ochtman.nl> =
wrote:
>>=20
>>> 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?
>>>=20
>>> 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.
>>>=20
>>>> 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.
>>>>=20
>>>> What is standing between here and there?
>>>>=20
>>>> What is there left to do before we can get the Sphinx work into =
master
>>> for
>>>> further iteration?
>>>=20
>>> 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.
>>>=20
>>> 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).
>>>=20
>>> Cheers,
>>>=20
>>> Dirkjan
>>>=20
>>>>=20
>>>> On Wed, Aug 1, 2012 at 12:28 PM, Dirkjan Ochtman =
<dirkjan@ochtman.nl>
>>> wrote:
>>>>=20
>>>>> 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?
>>>>>=20
>>>>> If we do, a proposed plan forward, with Dave and Robert N.:
>>>>>=20
>>>>> - 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
>>>>>=20
>>>>> 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.
>>>>>=20
>>>>> 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.
>>>>>=20
>>>>> Cheers,
>>>>>=20
>>>>> Dirkjan
>>>>>=20
>>>>=20
>>>>=20
>>>>=20
>>>> --
>>>> NS
>>>=20
>>=20
>>=20
>>=20
>> --
>> NS