couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Benoit Chesneau <bchesn...@gmail.com>
Subject Re: Docs, second try
Date Fri, 03 Aug 2012 03:47:43 GMT
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