Hi, what about reStructuredText? http://en.wikipedia.org/wiki/ReStructuredText
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
