You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@community.apache.org by Niclas Hedhman <ni...@hedhman.org> on 2015/07/01 17:43:08 UTC
Re: Hosting Searchable Release Specific Documentation
Well, in Apache Zest, we generate versioned documentation with the normal
build process, and that is then committed into the SVN site/content in its
own version-named directory. Documentation that is somewhat independent of
a release, such a "community stuff", are outside this.
Neo4j (not Apache) used a similar process and even generated the docs into
Maven artifacts, along with testsuite results.
Cheers
Niclas
On Tue, Jun 30, 2015 at 8:10 PM, Suresh Marru <sm...@apache.org> wrote:
> Hi All,
>
> 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 I
> could not trace all the links of projects using them, but [3] and [4] are
> examples). I read the thread on github pages [5], but it did not have a
> conclusive end.
>
> I am looking for something immediate, any suggestions please? It will be
> great if there is a precedence so we could just refer or even better
> plagiarize the scripts or approaches.
>
> Thanks,
> Suresh
>
> [1] - https://readthedocs.org/ <https://readthedocs.org/>
> [2] - http://en.flossmanuals.net/ <http://en.flossmanuals.net/>
> [3] - https://readthedocs.org/projects/cloudstack-administration/ <
> https://readthedocs.org/projects/cloudstack-administration/>
> [4] - https://readthedocs.org/projects/trafficserver/ <
> https://readthedocs.org/projects/trafficserver/>
> [5] - http://markmail.org/thread/bmbi65q7zdiej6dj <
> http://markmail.org/thread/bmbi65q7zdiej6dj>
>
>
--
Niclas Hedhman, Software Developer
http://zest.apache.org - New Energy for Java
Re: Hosting Searchable Release Specific Documentation
Posted by Suresh Marru <sm...@apache.org>.
On Thu, Jul 23, 2015 at 5:18 PM Dave Cottlehuber <dc...@apache.org> wrote:
> > > On Tue, Jun 30, 2015 at 8:10 PM, Suresh Marru <sm...@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.
>
Thank you Dave, I will follow closely couchdb release procedure document[1]
to find the mechanics. I will appreciate, If you happen to find a quick
reference on how and when the documents are published to readthedocs.org.
Thanks,
Suresh
[1] - https://cwiki.apache.org/confluence/display/COUCHDB/Release+Procedure
>
> A+
> Dave
>
>
Re: Hosting Searchable Release Specific Documentation
Posted by Dave Cottlehuber <dc...@apache.org>.
> > On Tue, Jun 30, 2015 at 8:10 PM, Suresh Marru <sm...@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
Re: Hosting Searchable Release Specific Documentation
Posted by zinhtut aung <zi...@gmail.com>.
On 1 Jul 2015 23:43, "Niclas Hedhman" <ni...@hedhman.org> wrote:
>
> Well, in Apache Zest, we generate versioned documentation with the normal
> build process, and that is then committed into the SVN site/content in its
> own version-named directory. Documentation that is somewhat independent of
> a release, such a "community stuff", are outside this.
>
> Neo4j (not Apache) used a similar process and even generated the docs into
> Maven artifacts, along with testsuite results.
>
> Cheers
> Niclas
>
> On Tue, Jun 30, 2015 at 8:10 PM, Suresh Marru <sm...@apache.org> wrote:
>
> > Hi All,
> >
> > 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
I
> > could not trace all the links of projects using them, but [3] and [4]
are
> > examples). I read the thread on github pages [5], but it did not have a
> > conclusive end.
> >
> > I am looking for something immediate, any suggestions please? It will be
> > great if there is a precedence so we could just refer or even better
> > plagiarize the scripts or approaches.
> >
> > Thanks,
> > Suresh
> >
> > [1] - https://readthedocs.org/ <https://readthedocs.org/>
> > [2] - http://en.flossmanuals.net/ <http://en.flossmanuals.net/>
> > [3] - https://readthedocs.org/projects/cloudstack-administration/ <
> > https://readthedocs.org/projects/cloudstack-administration/>
> > [4] - https://readthedocs.org/projects/trafficserver/ <
> > https://readthedocs.org/projects/trafficserver/>
> > [5] - http://markmail.org/thread/bmbi65q7zdiej6dj <
> > http://markmail.org/thread/bmbi65q7zdiej6dj>
> >
> >
>
>
> --
> Niclas Hedhman, Software Developer
> http://zest.apache.org - New Energy for Java