I've started to refactor current Camel K doc for Antora. Results are promising, I've rendered them in a temporary site https://www.nicolaferraro.me/website-experiments/. Website is rendered from [1] using the Antora default template, so I think it would look nicer with the official Camel template.
The only issue I've found so far is about links. I've used xref:module/thefile.adoc to add cross links between pages, but this way it's no more possible to navigate the adoc pages on github in [2]. That is fine, but this means we'll switch to Antora-based doc in Camel K only when the staging site is available (so we can point users to that from the README). Wdyt? Nicola Refs: [1]: https://github.com/nicolaferraro/website-experiments [2]: https://github.com/nicolaferraro/camel-k/tree/antora/docs/modules/ROOT/pages On Thu, Dec 13, 2018 at 7:56 AM Onder SEZGIN <ond...@apache.org> wrote: > Hi, > > Thanks Zoran, it is really great effort. > As i did not have experience with Antora and was following up with previous > effort where we used Hugo, webpack & gulp + ascii doctor. > Both approaches seems having trade-offs, i think better one is where we can > do progress as web-site under construction affects much of experience in > user experience terms especially when they start using any piece as > newbies. > > Still +1 and an will try to follow up with Antora approach and try to help > in the fields where i can. > > There is one point i am not %100 sure as we always say that documents will > be auto-generated from source code in asciidoc format and we also have > variosu other pages edited manually (especially examples for components). > After all these, are we going to keep all manually edited pages in > somewhere or we aim to drop them of from the offical documentation and have > them in somewhere else. > > And one note i have in terms of documentation, (there are of course quite a > lot of books) is that having doc pages around where different integration > flavours using even small pieces of camel would be very helpful. (of course > there is also blog posts, tutorials and etc... ). surely having such pages > and maintaining them will bring lots of doc management issues and maybe > JIRAs to follow up but in the longer run it will be a great doc base to > start using camel for devs at any level. and maybe maintaing those doc > bases with diffferent versions of camel and upgrading and fixing them is > also a bit of hassle but it will keep track of changes in different > integration styles and env. (CDI, Blueprint, Spring Boot, Karaf, > Standalone, Camel-K), etcc... Just an idea which may get deeper ?? > > Thanks again. > > Önder > > > On Wed, Dec 12, 2018 at 9:54 PM <m...@bennet-schulz.de> wrote: > > > Awesome Zoran! Great work!:) > > Am 12. Dez. 2018, 19:25 +0100 schrieb David Jencks < > > david.a.jen...@gmail.com>: > > > Hi Zoran, > > > > > > I don’t quite understand why, how, or where you are setting up symlinks > > for the components. Is there some reason not to put the expected antora > > directory structure inside each components expected maven directory > > structure and assemble them using antora? > > > > > > e.g. > > > > > > camel-*/src/main/doc/modules/component/pages/*.adoc > > > > > > I haven’t set up anything nearly this complicated with antora so I > could > > easily be missing something obvious :-) > > > > > > If this doesn’t work I’d be tempted to try to patch antora to work with > > maven directory structure, do you know if this is impractical? > > > > > > thanks > > > david jencks > > > > > > > > > > On Dec 12, 2018, at 3:10 AM, 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 > > > > > >
