On 27 Jan 2013, at 21:11, Zdeněk Henek <[email protected]> wrote: > Hi, > > what about reStructuredText? > http://en.wikipedia.org/wiki/ReStructuredText
Sounds like a valid alternative to AsciiDoc. I have a mild preference for AsciiDoc though because a fair few other JBoss projects have started using it and some tools/scripts can be reused. > > I have looked at some resources and found this: > > 1. github support reStructuredText - all documentation is viewable in > github repository too > https://gist.github.com/1855764 > source: > https://gist.github.com/raw/1855764/a4cdc598c46c5460a45560abc9934996de9388e1/README.rst > > 2. there is java support to generate pages from reStructuredText ( I > haven't tested this) > http://maven-site.nuiton.org/jrst/jrst-doc/en/index.html > > and it has maven plugin support => possible to build html/pdf > documentation as part of maven build > http://maven-site.nuiton.org/jrst/maven-jrst-plugin/en/index.html (I > haven't tested this) > > 3. could look like this: > > http://grok.zope.org/doc/current/tutorial.html > or other examples here > http://sphinx-doc.org/examples.html > > 4. there is http://sphinx-doc.org/index.html > in case the jrst project die or doesn't support all needed > documentation markup elements .... > > Regards, > Zdenek Henek > > > On Fri, Jan 25, 2013 at 10:15 AM, Galder Zamarreño <[email protected]> wrote: >> >> On Jan 24, 2013, at 2:51 PM, Manik Surtani <[email protected]> wrote: >> >>> Guys >>> >>> So one of the things coming soon is a revamped documentation site for >>> Infinispan. I am thinking of moving to AsciiDoc [1] in place of our >>> current Confluence [2] setup, so that documentation can be authored >>> offline, page loads will be much faster, etc. >>> >>> To see what the source files may look like, have a look at the source for >>> this guide to TicketMonster [3] and the corresponding rendered output [4]. >> >> Dan did some experiments last year and you can see some results here too: >> https://plus.google.com/114112334290393746697/posts/CdXJt6hVn5A >> >> Source: >> http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.asciidoc >> Result: http://mojavelinux.github.com/asciidoc-examples/javaeeworkshop.html >> >>> Now what I propose is a separate section in each maven module for >>> documentation (e.g., core/src/docs and cachestores/cloud/src/docs, etc) >>> which would contain an AsciiDoc page for each section. >>> >>> Then a root 'docs' folder to contain the table of contents and other >>> organisational attributes, and scripts in 'bin' to generate the >>> documentation. >> >> +1 >> >>> Further, I propose a separate git repository for the Infinispan website >>> (which will be modernised and moved to Awestruct), which in turn will have >>> build scripts to clone the infinispan repository, generate documentation, >>> and publish documentation alongside the website. >> >> ^ You probably want this to happen not only at publish time, but also when >> in developer mode? i.e. when you're in `awestruct -d` mode. Could be >> scripted of course. >> >>> Now this means the docs will not be editable online. So I propose again >>> using Disqus [5] to allow people to comment on each page of documentation, >>> which can then be updated as a pull request. >>> >>> Thoughts, comments? >> >> +1 to Disquss too. >> >>> >>> Cheers >>> Manik >>> >>> [1] http://www.methods.co.nz/asciidoc/ >>> [2] https://docs.jboss.org/author/display/ISPN/Home >>> [3] >>> https://raw.github.com/jboss-jdf/jdf-collateral/master/scripts/ticket-monster.asciidoc >>> [4] >>> https://github.com/jboss-jdf/jdf-collateral/blob/master/scripts/ticket-monster.asciidoc >>> [5] http://disqus.com/ >>> >>> -- >>> Manik Surtani >>> [email protected] >>> twitter.com/maniksurtani >>> >>> Platform Architect, JBoss Data Grid >>> http://red.ht/data-grid >>> >>> >>> _______________________________________________ >>> infinispan-dev mailing list >>> [email protected] >>> https://lists.jboss.org/mailman/listinfo/infinispan-dev >> >> >> -- >> Galder Zamarreño >> [email protected] >> twitter.com/galderz >> >> Project Lead, Escalante >> http://escalante.io >> >> Engineer, Infinispan >> http://infinispan.org >> >> >> _______________________________________________ >> infinispan-dev mailing list >> [email protected] >> https://lists.jboss.org/mailman/listinfo/infinispan-dev > > _______________________________________________ > infinispan-dev mailing list > [email protected] > https://lists.jboss.org/mailman/listinfo/infinispan-dev -- Manik Surtani [email protected] twitter.com/maniksurtani Platform Architect, JBoss Data Grid http://red.ht/data-grid _______________________________________________ infinispan-dev mailing list [email protected] https://lists.jboss.org/mailman/listinfo/infinispan-dev
