Thanks Mark. Regarding maintenance, it will be as easy as the current version. Updating docs means updating markdown files. Adding/moving pages requires to modify the `SUMMARY.md` but that's it. One really cool thing is that Gitbook is a node app: really simple to install/run compare to our current solution which runs only on an old version of ruby => no more pain of using different versions of ruby on your environment.
In terms of feature gaps, Gitbook provides the same or more features than Jekyll out the box: - search! That is a big one, not available with Jekyll - include of external files - syntax highlighting - plugins system - custom theme Best. On Sat, 7 Oct 2017, 17:10 Mark McKenna, <m4rkmcke...@apache.org> wrote: > Thomas this looks really clean great work. > > How much work do you think it will take to maintain vs our current > solution? > What do you see as being the current feature gaps? > > M > > On Fri, 6 Oct 2017 at 14:55 Thomas Bouron <thomas.bou...@cloudsoftcorp.com > > > wrote: > > > Hi Richard. > > > > Of course, I pushed it to my fork on the branch `experiment/gitbook`[1] > > Glad you like it :) > > > > Best. > > > > [1] https://github.com/tbouron/brooklyn-docs/tree/experiment/gitbook > > > > On Fri, 6 Oct 2017 at 13:53 Andrea Turli <and...@cloudsoft.io> wrote: > > > > > +1 Thomas, didn't know Gitbook at all (that's why I suggested > > readthedocs) > > > but looks pretty good! > > > > > > Il 06/ott/2017 15:37, "Richard Downer" <rich...@apache.org> ha > scritto: > > > > > > Hi Thomas, > > > > > > I withdraw my previous comments - I looked at ReadTheDocs last year and > > was > > > pessimistic, but it seems that GitBook this year is a different story > :-) > > > > > > This is worth pursuing IMO. What did you need to do to get this > working? > > > Did you have to do any work on the brooklyn-docs source - if so could > you > > > share a link to your repo? > > > > > > Thanks > > > Richard. > > > > > > > > > On 6 October 2017 at 13:18, Thomas Bouron <thomas.bouron@cloudsoftcorp. > > com > > > > > > > wrote: > > > > > > > Hi All. > > > > > > > > A demo is worth a thousand words so here is a gitbook adaptation of > our > > > > current documentation[1] (and only documentation) > > > > This took me only a couple of hours. There are still things to > > > > fix/update/remove like unsupported liquid tags but for the most part, > > it > > > > works like a charm. > > > > Search is available from the search field on the top left and PDF[2], > > > > epub[3] amd mobi[4] versions are also available. > > > > The build took only 10 sec + 10 more per offline version. > > > > > > > > The table of content mirrors exactly what we currently have, except > > that > > > I > > > > have limited it to only 2 sub-levels. It means that some pages are > > > missing > > > > but I think it demonstrates that our current menu organisation could > be > > > > vastly improved. > > > > > > > > Couple of thoughts on Alex's points: > > > > > > > > > * for the examples, import source code that is actually used in > tests > > > > (!!!) > > > > > > > > Indeed, an overhaul does not solve it, nor our current framework. But > > > both > > > > can implement it. > > > > > > > > > * check links > > > > > > > > Gitbook checks internal links at compile time and refuses to build if > > > > something is wrong. AFAIK, there is nothing in the Gitbook world to > > check > > > > the validity of external links like the Jekyll plugin does. There are > > > > probably external tools that we can integrate in our build pipeline > to > > > > cover this. However, it seems that even if we have this tool, we > don't > > > use > > > > it when pushing the website (as I get a lot of errors locally) > > > > Realistically, we will always have broken links, things move around > all > > > the > > > > time. Checking external links is a nice-to-have but far from being a > > > > perfect solution. In any case, I don't see this point as important as > > you > > > > do. > > > > > > > > > * think through user flow > > > > > > > > The clear Gitbook menu exposes this pretty well IMO and better > compared > > > to > > > > the current version so that's a win. > > > > > > > > Best. > > > > > > > > [1] https://tbouron.github.io/brooklyn-docs/ > > > > [2] https://tbouron.github.io/brooklyn-docs/brooklyn.pdf > > > > [3] https://tbouron.github.io/brooklyn-docs/brooklyn.epub > > > > [4] https://tbouron.github.io/brooklyn-docs/brooklyn.mobi > > > > > > > > > > > > On Thu, 5 Oct 2017 at 12:47 Richard Downer <rich...@apache.org> > wrote: > > > > > > > > > Thank you for the research you have done Thomas. I've had similar > > > > thoughts > > > > > myself. The original goal of our web+docs was to integrate them in > > such > > > a > > > > > way that we had a versioned user guide that integrated perfectly > with > > > the > > > > > main website. At the time, Markdown tools were relatively immature, > > > with > > > > > Jekyll leading the pack (and being the fashionable choice), and > very > > > > little > > > > > in the way of viable apps for generating books with structure and > > > tables > > > > of > > > > > contents. We did the best we could with the tools we had, but they > > > needed > > > > > significant extensions (via Jekyll plugins and build scripting). > > Those > > > > > plugins and scripts have turned into something fairly hairy - IMO > we > > > > > shouldn't need to have to write this much code[1] to generate a > > static > > > > site > > > > > and manual. With hindsight, I would not have argued in favour of > this > > > > > model. If I do write my book[2] I will most likely be writing it in > > > > > ReStructuredText and processing it with Sphinx (and no additional > > > > > scripting/tooling!). > > > > > > > > > > That said, when I have looked at changing Brooklyn's documentation > > > > system, > > > > > it has not looked easy. With our home-grown TOC generating code, > > we're > > > > not > > > > > off-the-shelf compatible with other systems. Moving to another > > system, > > > > even > > > > > if it is Markdown-based, would still involve a lot of manual work > > > > changing > > > > > our document metadata to the new system, and adapting to replace > the > > > > Jekyll > > > > > plugins and the content that uses them (e.g. syntax highlighting, > > file > > > > > inclusion). Unless you have discovered something I didn't, Thomas, > > then > > > I > > > > > fear this will be a lot of work, mostly manual. > > > > > > > > > > In short, yes I like the idea of replacing our home-grown and > > > > > home-maintained code with an existing and supported app, but no I > > don't > > > > > think the effort of a big-bang migration justifies the results *at > > this > > > > > time*. > > > > > > > > > > Some things I would support: > > > > > > > > > > - Continued incremental improvements to both the website and the > user > > > > > guide. IMO we have more problems with the content than with the > > > tooling, > > > > > and we can still make a lot of improvements to the usability of our > > > docs > > > > > and website without tooling changes. > > > > > > > > > > - Breaking the tight integration between website and user guide. > > "Fork" > > > > the > > > > > existing infrastructure but then have two build systems tailored > for > > > > their > > > > > purpose rather than one that tried to meet two different needs. > Would > > > > allow > > > > > the existing stuff to continue to work while opening the door to > > > > replacing > > > > > the guide tooling and redeveloping the website, independently of > each > > > > > other, at a future date. > > > > > > > > > > - Evaluating how other systems use metadata to describe the book > > > > structure, > > > > > and gradually adding support for this to our own tools and > migrating > > > > > content. Then at a later date, when the content is > nearly-compatible > > > with > > > > > GitBook or some other system, it'll be easier to do the migration. > > > > > > > > > > What do you think? Will following an incremental approach like this > > > allow > > > > > us to make improvements gradually rather than a "big bang" > > replacement > > > of > > > > > tooling? > > > > > > > > > > Richard. > > > > > > > > > > [1] > https://gist.github.com/rdowner/a09a268b37904a03c452797e7afe56ca > > > but > > > > > consider the COCOMO figures with appropriate cynicism > > > > > [2] > > > > > > > > > > > https://lists.apache.org/thread.html/6f19475bbc0570a3b9e3d1ae1b75b2 > > > > b8ee4b2485b3b41d085c342dff@%3Cdev.brooklyn.apache.org%3E > > > > > > > > > > On 5 October 2017 at 11:23, Thomas Bouron > > <thomas.bouron@cloudsoftcorp. > > > > com > > > > > > > > > > > wrote: > > > > > > > > > > > Hi all. > > > > > > > > > > > > It's been a couple of weeks that I started to look at how to > > improve > > > > and > > > > > > simplify the Brookyln website[1]. As I said on the Brooklyn 1.0 > > > > > thread[2], > > > > > > I think we need to sort this out before releasing 1.0. > > > > > > > > > > > > I have looked for a framework / library to handle both the > website > > > and > > > > > > documentation the same way we do it right now. To determine what > > was > > > > the > > > > > > best fit, I based my analysis on the following criteria: > > > > > > - Able to take markdown files and generate HTML from them. > > > > > > - Keep the folder structure intact (currently, pages that seems > in > > > the > > > > > same > > > > > > logical group - take pages in the download section[3] menu - jump > > > into > > > > a > > > > > > different folder/category/section which is very confusing) > > > > > > - Be skinnable > > > > > > - Able to handle versions for documentation. > > > > > > - Able to generate PDF version of documentation. > > > > > > - Be as "stock" as possible to limit maintenance and pain during > > > > upgrade > > > > > > (our current website still uses Jekyll 2.x). > > > > > > > > > > > > 2 contenders clearly jumped out from this: > > > > > > - Jekyll[4] > > > > > > - Gitbook[5] > > > > > > > > > > > > ---- > > > > > > Jekyll > > > > > > > > > > > > With the version 3, Jekyll now has a concept of collections[6] > > which > > > > can > > > > > > generate pages from markdown files and keep the folder structure. > > > > > > The menu can be generated based on this folder structure (with > > depth > > > > > > limitation for example) in combination of some clever liquid tags > > and > > > > > > `include`. However, it will be hard to control the order of items > > > > > appearing > > > > > > on the menu. Another easy solution would be maintain list of > links > > > for > > > > > the > > > > > > menu to be generated. > > > > > > There are plugins to generate PDF[7], which happens during > compile > > > > time. > > > > > > Finally, Jekyll is highly skinnable with built-in or custom > themes. > > > > > > > > > > > > ---- > > > > > > Gitbook > > > > > > > > > > > > Gitbook, in its open source version, handles out of the box doc > > > > > versioning, > > > > > > PDF generation at runtime (so it seems) HTML pages generation > from > > > > > > markdown. The menu is built-in feature, based on a simple > markdown > > > list > > > > > of > > > > > > links[8]. This means we need to maintain it but there is a good > > > chance > > > > we > > > > > > will have to do this with Jekyll as well. Finally, Gitbook is > also > > > > easily > > > > > > skinnable[9]. > > > > > > > > > > > > ---- > > > > > > Both frameworks offer mostly the same features. However, Jekyll > is > > > > easier > > > > > > to build a website that looks like a "corporate" one whereas with > > > > > Gitbook, > > > > > > you are "stuck" with the design principals it was created, i.e. > > serve > > > > > > documentation only. But for this very purpose, it is extremely > good > > > and > > > > > > easy. > > > > > > > > > > > > Our website is the combination of both a "corporate website" > (i.e. > > > > about, > > > > > > getting started, community, etc - few pages that describe the > > > project) > > > > > and > > > > > > a documentation. > > > > > > > > > > > > Which leads me to my proposal: separate the website from the > > > > > documentation, > > > > > > at least in terms of how we build it. What I mean by this is: > > > > > > - Use Jekyll (or even nothing) for the website, except the > > > > documentation > > > > > > part. This will let us build a nice theme (based on Bootstrap 4 > for > > > > > > example) without to worry about complicated plugins and custom > code > > > for > > > > > the > > > > > > documentation. > > > > > > - Use Gitbook for the documentation alone, applying/adapting the > > > theme > > > > we > > > > > > will create from the point above. > > > > > > > > > > > > Best. > > > > > > > > > > > > [1] https://brooklyn.apache.org/ > > > > > > [2] > > > > > > https://lists.apache.org/thread.html/ > > dae4468aa7ef77af9dc8aca24b8434 > > > > > > e9782efbd50fa876618cccf980@%3Cdev.brooklyn.apache.org%3E > > > > > > [3] https://brooklyn.apache.org/download/index.html > > > > > > [4] https://jekyllrb.com/ > > > > > > [5] https://github.com/GitbookIO/gitbook > > > > > > [6] https://jekyllrb.com/docs/collections/ > > > > > > [7] http://abemedia.co.uk/jekyll-pdf/ > > > > > > [8] https://toolchain.gitbook.com/pages.html > > > > > > [9] https://toolchain.gitbook.com/themes/ > > > > > > -- > > > > > > > > > > > > Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation > • > > > > > > https://cloudsoft.io/ > > > > > > Github: https://github.com/tbouron > > > > > > Twitter: https://twitter.com/eltibouron > > > > > > > > > > > > > > > -- > > > > > > > > Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation • > > > > https://cloudsoft.io/ > > > > Github: https://github.com/tbouron > > > > Twitter: https://twitter.com/eltibouron > > > > > > > > > -- > > > > Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation • > > https://cloudsoft.io/ > > Github: https://github.com/tbouron > > Twitter: https://twitter.com/eltibouron > > > -- Thomas Bouron • Senior Software Engineer @ Cloudsoft Corporation • https://cloudsoft.io/ Github: https://github.com/tbouron Twitter: https://twitter.com/eltibouron
