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 > -- Apache Member Apache Karaf <http://karaf.apache.org/> Committer & PMC OPS4J Pax Web <http://wiki.ops4j.org/display/paxweb/Pax+Web/> Committer & Project Lead blog <http://notizblog.nierbeck.de/> Co-Author of Apache Karaf Cookbook <http://bit.ly/1ps9rkS> Software Architect / Project Manager / Scrum Master
