Boost logo

Boost :

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Kris (krzysztof_at_[hidden])
Date: 2016-02-25 16:07:40

> On Thursday, February 25, 2016 at 9:18:28 AM UTC-6, Krzysztof Jusiak wrote:
> On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart <rob.s...@
&gt; <javascript:>>
> wrote:
> > On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak <
> > krzy...@ <javascript:>> wrote:
> > > Dear Boosters,
> > >
> > > I'm writing to ask about your opinion regarding more interactive
> > > documentation for Boost.
> > [snip]
> > > I would like to know what the Boost community thinks
> > > about having following
> > > features in the documentation...
> > >
> > > * Run the code online (allows to check library with one click)
> >
> > I see no value in that. The library is supposed to be in good working
> > order and I wouldn't care to verify that from the docs. Instead, I'd
> expect
> > a link to where such things can be viewed and managed.
> >
> > I just looked at the DI docs and I now see that you meant being able to
> > run sample code shown in the docs. If the sample program was somehow
> > interactive or the code was editable such that one could experiment with
> > it, then I can see the value.
> >
> > Your "Run this code!" button hides some of the code!
> >
> Yea, that was my point for the user to be able to easily experiment before
> really trying the library. A lot of users won't download the library and
> check it out, but IMHO, some of them
> may actually click the button and check what will happen. Moreover, some
> users (me, for example) when see code example are curious what will happen
> if...
> Documentation will not cover all cases, but if user can quickly check it
> might be beneficial, I think.
> If it comes to interaction itself, I was thinking of creating an
> interactive tutorial for the users. For example, a lot of people do not
> see
> benefits in dependency injection and having
> a quick exercise to adopt code with or without DI could have changed their
> mind.
> One of the examples where user can interact a bit more...
> > > * Comments (allows commenting on the documentation)
> >
> > I can understand that comments would permit quick notes on what's
> lacking
> > or unclear, but I also wouldn't want comment loading to slow page
> loading
> > or for their display to detract from the information. Thus, having a
> means
> > to display them, on demand, probably with a sticky bit, would be a
> > reasonable compromise.
> >
> Point taken. Therefore, I have prepared 3 themes for the users.
> * Boost-Experimental - the fancy one -
> * Boost-Modern - more like Boost but still interactive -
> * Boost - classic Boost (no Java Script) -

> BTW, my boost theme still uses javascript for syntax highlighting. I would
> like to add a variable to disable javascript highlighting(or perhaps pick
> a
> different highlighting theme). This way the user could highlight using
> pygments
> instead if they wanted to.

That would be great!

>Also, the theme can be installed using `pip install mkdocs-boost`. And then
>the docs can be built by setting the theme to `boost` either on the command
>line or in the yaml file:
> mkdocs build -t boost
>This way you don't have to drag around the boost theme directory.

Wow, that's cool. However, I have made quite a few modifications to the
original theme
in order to support tables, theme selection and added (optionally) all Java
Script magic.
Moreover, I have removed a lot of not needed files from the theme. When the
look and feel
of the spec will be approved by the boost users I will create a pull request
so that you can
check what I have changed. Thanks again for a great job on the boost-theme!

> Paul

View this message in context:
Sent from the Boost - Dev mailing list archive at

Boost list run by bdawes at, gregod at, cpdaniel at, john at