Hi Wim,
First of all, a very nice experiment: our documentation could use a bit of an overhaul, so thanks for your effort in starting the discussion and coming up with an alternative solution. Although Scalate has served us in the past, it is not the most straightforward experience for a novice user, so if switching to something else makes it easier for people to contribute to the docs, that's great. I did take a look at the two guides you ported and those .rst files look really straightforward - nice little touch with the CSS based terminal "screenshots" btw. Also, installing the tooling and running a simple "make html" was a real breeze compared to the current process. Integrating this with the Apache infrastructure shouldn't be a problem, since I found a few other projects (libcloud, cloudstack, trafficserver, ...) at the ASF that are already using this and have docs built automatically by Buildbot. Personally, I don't have any experience with neither Sphinx nor Asciidoctor, so I can't really compare. If other people think AsciiDoctor is better solution, perhaps someone should do a similar experiment and port the same two guides to AsciiDoc so we actually have something to compare? Regards, Gert Vanthienen On Sat, Jan 24, 2015 at 12:49 AM, Wim Verreydt <[email protected]> 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
