Yeah, the approach seems good! I'll start to prepare Camel K to provide documentation in the form Antora expects, so we can merge it in the main Camel website. We already have some doc pages in the .adoc format, we need to organize them better.
Nicola On Wed, Dec 12, 2018 at 3:28 PM Andrea Cosentino <ancosen1...@yahoo.com.invalid> wrote: > Very well done Zoran, thanks! > > -- > Andrea Cosentino > ---------------------------------- > Apache Camel PMC Chair > Apache Karaf Committer > Apache Servicemix PMC Member > Email: ancosen1...@yahoo.com > Twitter: @oscerd2 > Github: oscerd > > > > > > > On Wednesday, December 12, 2018, 12:10:33 PM GMT+1, Zoran Regvart < > zo...@regvart.com> wrote: > > > > > > Hi Cameleers, > I've found some time to work on the website and here's the current > status on the progress we made. > > We had some great contributions on the new website raging from the > Asciidoctor theme and build for the user manual that Francois > contributed, to the wiki pages migration that Alex, Andrea, Claus, > Gregor, Pascal, Önder, Satyajit, Tadayoshi and Willem did (I'm sorry > if I'm forgetting anyone). > > This started as an effort on the `website` branch where I tried to > create a static build of the website using Hugo, a custom-built > wrapper for Asciidoctor and a bunch of Gulp+Webpack tasks to tie it > all together. That resulted in complex, slow to build and, obviously, > for anyone besides me hard to contribute and comprehend ball of mud. > > I'm going to abandon that effort, and in turn focus on a (I think) > simpler approach. > > The new approach is already looking (to me) much better in terms of > simplicity and maintanability, and I'm about to polish it a bit and > push it so that anyone can take a look and comment on it. > > I've focused on a Antora[1] based website build for the User manual > and the Component reference -- this has great benefits of having > support for documentation version out of the box. This way we can have > the component reference built from different Camel versions (release > branches). > > It is not without (some, I'd argue small) complexity, I needed to move > files comprising the user manual and I've created a Gulp build that'll > create directory structure Antora expects by creating symlinks from > this directory structure to `component/camel-*/src/main/doc/*.adoc`. > The end result is that we'll have symbolic links in the git > repository, not sure if that's controversial, but it could be > surprising for some. We could also move the component documentation > from component Maven modules into a single Antora directory structure > and that's something we can evaluate as well. > > Next, I've build an Antora theme, basically by forking the default > theme and adding fonts and text styling that Francois created for the > ASF Asciidoctor theme. This part still needs a lot of work to make it > look much nicer. > > I'm now in the process of combining Hugo for the content besides the > documentation, like main page, release notes, blog/news. > > Another thing is that I'll be moving the website from the camel git > repository to the camel-website git repository, which will now contain > the build scripts, all content besides the user manual and the > component documentation and the Antora theme. > > I think I'll start merging to the master from the website branch as > soon as the the work stabilizes a bit to help with the visibility of > this work and to make it easier for other contributors to make > changes. > > I would like to say that I think we're getting close to the new > website with this new approach, and as always I very much welcome any > comment or any other contribution in this effort. I'll be cleaning up > the JIRA issue[2] and adding more tasks for anyone to pick up. > > Nothing is set in stone if anyone has a better idea of going about > this feel free to comment :) > > I'll be posting updates on this thread as I progress on this, my goal > is to have a rough version of the website (by rough I mean, some links > not working, very basic design and topology) done by Christmas. > > zoran > > [1] http://antora.org/ > [2] https://issues.apache.org/jira/browse/CAMEL-11492 > -- > Zoran Regvart >
