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

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... 
> 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.

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: http://boost.2283326.n4.nabble.com/doc-Liven-up-Boost-Documentation-with-Java-Script-tp4683773p4683828.html
Sent from the Boost - Dev mailing list archive at Nabble.com.