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 12:21:10 GMT
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

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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message