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 Wed, 01 Aug 2012 04:44:14 GMT
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
>

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