incubator-couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Robert Newson <>
Subject Re: Docs, second try
Date Fri, 03 Aug 2012 11:50:21 GMT

The docs should be hosted on imo.


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

> On Wed, Aug 1, 2012 at 2:21 PM, Noah Slater <> 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
> I'm trying to summarize the actions we need to put in place here:
> 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)
> Where do we host the doc?
> - 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 ?
> - both
> 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?
> - benoit
>> On Wed, Aug 1, 2012 at 1:07 PM, Dirkjan Ochtman <> wrote:
>>> On Wed, Aug 1, 2012 at 2:00 PM, Noah Slater <> 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 <>
>>> wrote:
>>>>> On Wed, Aug 1, 2012 at 1:11 PM, Dave Cottlehuber <>
>>> 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
>>>>> 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
>>>>> think this would be a great way to move forward.
>>>>> Cheers,
>>>>> Dirkjan
>>>> --
>>>> NS
>> --
>> NS

View raw message