community-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Cottlehuber <...@apache.org>
Subject Re: Hosting Searchable Release Specific Documentation
Date Thu, 23 Jul 2015 21:18:16 GMT
> > On Tue, Jun 30, 2015 at 8:10 PM, Suresh Marru <smarru@apache.org> wro
> > > Can I get some advice on how projects deal with hosting release specific
> > > documentation? In addition to the CMS and Wiki, I am exploring
> alternatives
> > > which have a good search built-in. I preciously came across ASF projects
> > > hosting documentation on read the docs [1] and floss manuals [2] (sorry


hi Suresh

For Apache CouchDB, we use sphinx & also readthedocs to generate
content, from .rst files, included in the source code itself up until
2.0, which uses a separate repo as the source code now is built from a
set of smaller code modules.

Either way, they are processed & bundled into the source tarball at
release creation time and, directly available from the couchdb instance
itself when it's installed - a nice feature as the right version of docs
is always to hand.

sphinx provides searchtools.js which knows how to use the inverted index
generated during build time. This works pretty well in my experience.

readthedocs.org is awesome and I suspect a number of projects could
benefit from a similar sort of toolchain. It just adds the new version's
docs alongside the old ones with a toggle switch in the top corner to
switch version, every time we push a new release out. I forget the exact
mechanism, but IIRC its a new signed tag in the main repo.

A+
Dave


Mime
View raw message