Good point.
Regards
JB
On 01/24/2015 07:20 PM, Achim Nierbeck wrote:
Hi
actually I'd prefer to switch to asciidoctor. For Pax Web I switched to it.
There is actually a script available that converts Confluence wiki syntax
to Asciidoctor.
With the asciidoctor maven plugin we could generate a) a pdf and b) a html
syntax which we could also push via svnpupsub.
Since it's just asciidoc files I think those also can be pulled in from a
github source.
For example take a look at the new [1] and the old [2] Pax Web
Documentation.
Regards, Achim
[1] - http://ops4j.github.io/pax/web/4.0.2/
[2] - https://ops4j1.jira.com/wiki/display/paxweb/Documentation
2015-01-24 8:21 GMT+01:00 Jean-Baptiste Onofré <[email protected]>:
Hi Wim,
Currently, SMX uses scalate for doc, with a wiki like syntax. It allows
use to use the documentation from the other projects that use it (like
Karaf).
I'm not against changing, but it means:
1/ if we talk about look'n feel, we don't need a change in the framework
used: I already proposed some improved scalate template
2/ it means to "migrate" and change the existing: I have no problem with
that
3/ I have to double check that there's no problem with mvn scm-publish:
it's the Apache way to publish the documentation. It's the key part that I
would like to double check.
4/ we use princexml for PDF generation, just to check if we lose the PDF
export or not (not a big deal IMHO)
I will review your github and give you a complete feedback.
Regards
JB
On 01/24/2015 12:49 AM, Wim Verreydt wrote:
Hi,
A while ago I figured that the ServiceMix documentation could use an
upgrade. Instead of fixing everything I took the chance to experiment with
some suitable frameworks like Middleman, Jekyll and Sphinx.
The first two did not really made thing easier but Sphinx (
http://sphinx-doc.org/) seems like a big improvement. It is beïng used
in a lot of non-python projects these days so it should lower the learning
curve an effort to contribute documentation.
I started out with the well known theme provided by readthedocs.org (
https://github.com/snide/sphinx_rtd_theme) and added some custom
functionality like an terminal window in CSS that should replace the
screenshots in our current documentation.
Just to test I ported the first two guides of the ServiceMix
documentation.
You can find the project at https://github.com/wimve/smx-doc-sphinx and
a html build at https://dl.dropboxusercontent.
com/u/1528761/smx-doc-sphinx/index.html
Let me know what you think! If this is considered to be an improvement
I'll continue to port the rest of our guides.
Regards,
Wim Verreydt
--
Jean-Baptiste Onofré
[email protected]
http://blog.nanthrax.net
Talend - http://www.talend.com
--
Jean-Baptiste Onofré
[email protected]
http://blog.nanthrax.net
Talend - http://www.talend.com
