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