Re: [boost] [doc] Liven up Boost Documentation with Java Script?

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Paul Fultz II (pfultz2_at_[hidden])
Date: 2016-02-25 13:08:28

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..._at_[hidden] 
> <javascript:>> 
> wrote: 
>
> > On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < 
> > krzy..._at_[hidden] <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... 
> http://boost-experimental.github.io/di/extensions/index.html#types-dumper 
>
>
> > > * 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 - 
> http://boost-experimental.github.io/di 
> * Boost-Modern - more like Boost but still interactive - 
> http://boost-experimental.github.io/di/boost-modern/ 
> * Boost - classic Boost (no Java Script) - 
> http://boost-experimental.github.io/di/boost/

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.

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.

Paul