incubator-couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Noah Slater <nsla...@tumbolia.org>
Subject Re: Docs, second try
Date Wed, 01 Aug 2012 10:52:25 GMT
(For reference, Benoît, Sphinx happily satisfies option 1.)

On Wed, Aug 1, 2012 at 5:44 AM, Benoit Chesneau <bchesneau@gmail.com> 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 <bchesneau@gmail.com
> <javascript:;>>
> > wrote:
> >
> > > On Tue, Jul 31, 2012 at 10:23 PM, Dirkjan Ochtman <dirkjan@ochtman.nl
> <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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message