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-26 10:35:45

On Thursday, February 25, 2016 at 3:34:22 PM UTC-6, Kris wrote:
>
> > 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! 
>

Ah yes, tables is something that needs improving. I was working with the 
boost
CSS, and it doesn't seem to have anything for css tables. I think boost book
styles the tables with HTML. I'll take a look at what you did for tables and
try to integrate that in.

Also, mkdocs will include automatically all javascripts files in the
documentation source directory, plus additional files can be included using
the `extra_javascript`.  However, I don't know if the boost theme supports
this yet(I haven't had a need for it yet), but it should be supported. 
Plus, I
think this might be a good place for some of the javascript until it gets
official approval in boost.
 
Paul