Mailing-List: contact dev-help@brooklyn.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@brooklyn.apache.org
MIME-Version: 1.0
In-Reply-To: <CAH20XTYgGLTM49uWdvS_r_pjf6WwrEiYJ3VeQLGus=5Oc-NiOg@mail.gmail.com>
References: <CAH20XTZ41g8yBayYPQYFtdQa=gHLzajQbzYnWVk-ZkFLWiovrg@mail.gmail.com>
 <CABQFKi3mSLZvHveEyU9LmBjX-jMjuRY_jfWtFSRGOtyV1NZYYw@mail.gmail.com>
 <CAH20XTZDyoFfCRP4YoQ2t0V+FneTWHNRLzoybxRWwkN3sZnnBw@mail.gmail.com>
 <CABQFKi2zAoM251EMFghS-uy-BdOE0dRZ89e3u05U_SAypZJoUA@mail.gmail.com>
 <CANaN7bFqD6yb3oRwuaT+Y8o8UTm9bWENuOn32iTKKvwHPsYnag@mail.gmail.com>
 <CANaN7bHsLcuZskVra74xuWZr2_ZO-NwbHfDXnZ_Gd_Z=irE70A@mail.gmail.com> <CAH20XTYgGLTM49uWdvS_r_pjf6WwrEiYJ3VeQLGus=5Oc-NiOg@mail.gmail.com>
From: Mark McKenna <m4rkmckenna@apache.org>
Date: Sat, 7 Oct 2017 17:09:43 +0100
Message-ID: <CABKEZSY02TQFGJ=4CtDH2rWB3fJADG1xv1rOd66bRgDGFs1+2g@mail.gmail.com>
Subject: Re: [PROPOSAL] Split Brooklyn website and documentation
To: Brooklyn dev <dev@brooklyn.apache.org>
Content-Type: multipart/alternative; boundary="089e082904c0ded3fd055af731d2"
archived-at: Sat, 07 Oct 2017 16:10:28 -0000

--089e082904c0ded3fd055af731d2
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

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.bouron@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 <andrea@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" <richard@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 y=
ou
> > 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 o=
ur
> > > 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 tes=
ts
> > > (!!!)
> > >
> > > 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 t=
o
> > > 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 a=
ll
> > 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 compar=
ed
> > 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 <richard@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 wi=
th
> > the
> > > > main website. At the time, Markdown tools were relatively immature,
> > with
> > > > Jekyll leading the pack (and being the fashionable choice), and ver=
y
> > > 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 w=
e
> > > > 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 th=
is
> > > > 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 th=
e
> > > 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 us=
er
> > > > 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 fo=
r
> > > their
> > > > purpose rather than one that tried to meet two different needs. Wou=
ld
> > > allow
> > > > the existing stuff to continue to work while opening the door to
> > > replacing
> > > > the guide tooling and redeveloping the website, independently of ea=
ch
> > > > 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 migratin=
g
> > > > content. Then at a later date, when the content is nearly-compatibl=
e
> > 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/a09a268b37904a03c452797e7afe56c=
a
> > 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 websit=
e
> > 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 i=
n
> > 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 link=
s
> > for
> > > > the
> > > > > menu to be generated.
> > > > > There are plugins to generate PDF[7], which happens during compil=
e
> > > time.
> > > > > Finally, Jekyll is highly skinnable with built-in or custom theme=
s.
> > > > >
> > > > > ----
> > > > > Gitbook
> > > > >
> > > > > Gitbook, in its open source version, handles out of the box doc
> > > > versioning,
> > > > > PDF generation at runtime (so it seems) HTML pages generation fro=
m
> > > > > markdown. The menu is built-in feature, based on a simple markdow=
n
> > 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 als=
o
> > > easily
> > > > > skinnable[9].
> > > > >
> > > > > ----
> > > > > Both frameworks offer mostly the same features. However, Jekyll i=
s
> > > 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 go=
od
> > 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 f=
or
> > > > > example) without to worry about complicated plugins and custom co=
de
> > 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 =E2=80=A2 Senior Software Engineer @ Cloudsoft Corp=
oration =E2=80=A2
> > > > > https://cloudsoft.io/
> > > > > Github: https://github.com/tbouron
> > > > > Twitter: https://twitter.com/eltibouron
> > > > >
> > > >
> > > --
> > >
> > > Thomas Bouron =E2=80=A2 Senior Software Engineer @ Cloudsoft Corporat=
ion =E2=80=A2
> > > https://cloudsoft.io/
> > > Github: https://github.com/tbouron
> > > Twitter: https://twitter.com/eltibouron
> > >
> >
> --
>
> Thomas Bouron =E2=80=A2 Senior Software Engineer @ Cloudsoft Corporation =
=E2=80=A2
> https://cloudsoft.io/
> Github: https://github.com/tbouron
> Twitter: https://twitter.com/eltibouron
>

--089e082904c0ded3fd055af731d2--