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
