couchdb-dev mailing list archives

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

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
> 
> 
> 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 docs.couchdb.org ?
> - 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 <dirkjan@ochtman.nl> wrote:
>> 
>>> 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
>>> 
>> 
>> 
>> 
>> --
>> NS


Mime
View raw message