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 >
