Sorry guys! It was literally in bed half asleep when I sent that! ^_^ The RST stuff looks slick as fuck. Are we ready to merge this in to our main repos? I love it.
Just double checked the Pandoc docs, and we can convert the rst in to Texinfo. So, we have two options from here: - Convert this in to Texinfo, and let Autotools handle info pages, PDF, PS, etc, or... - Use Sphinx to generate everything (as it seems to be able to) and just hook that up to Autotools Now, I am a hardcore Autotools nut, but I think using Sphinx to convert into our output formats may yeild the best results, as Sphinx is more likely to produce consistent formatting across all of them. We can then just use Autotools to drop the files in to the right places. So, if we can merge this work in to share/docs, I can hook it in to Autotools. (Which should include integration with the build, and installing into Futon, etc, etc.) On Wed, Aug 1, 2012 at 5:44 AM, Benoit Chesneau <[email protected]> wrote: > On Wednesday, August 1, 2012, Noah Slater 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. > > > > > > > > > i'm confused. Siunds like this mail ignore the current result using > sphinx.... What do you think about that work? What compared to these 2 > options ? > > benoît > > > On 31 Jul 2012, at 22:22, Benoit Chesneau <[email protected] > <javascript:;>> > > wrote: > > > > > On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <[email protected] > <javascript:;>> > > 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 > > > -- NS
