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

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 javascript:> wrote:

...

On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzy...@jusiak.net 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