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/a4cdc598c46c5460a45560abc9934996de938...
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 <galder(a)redhat.com> wrote:
>
> On Jan 24, 2013, at 2:51 PM, Manik Surtani <manik(a)jboss.org> 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-mon...
>> [4]
https://github.com/jboss-jdf/jdf-collateral/blob/master/scripts/ticket-mo...
>> [5]
http://disqus.com/
>>
>> --
>> Manik Surtani
>> manik(a)jboss.org
>>
twitter.com/maniksurtani
>>
>> Platform Architect, JBoss Data Grid
>>
http://red.ht/data-grid
>>
>>
>> _______________________________________________
>> infinispan-dev mailing list
>> infinispan-dev(a)lists.jboss.org
>>
https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
>
> --
> Galder Zamarreño
> galder(a)redhat.com
>
twitter.com/galderz
>
> Project Lead, Escalante
>
http://escalante.io
>
> Engineer, Infinispan
>
http://infinispan.org
>
>
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev(a)lists.jboss.org
>
https://lists.jboss.org/mailman/listinfo/infinispan-dev
_______________________________________________
infinispan-dev mailing list
infinispan-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev