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]
> > On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak <
> > > 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
> > 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
> 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
> benefits in dependency injection and having
> a quick exercise to adopt code with or without DI could have changed their
> One of the examples where user can interact a bit more...
> > > * Comments (allows commenting on the documentation)
> > I can understand that comments would permit quick notes on what's
> > or unclear, but I also wouldn't want comment loading to slow page
> > or for their display to detract from the information. Thus, having a
> > 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 -
> * Boost-Modern - more like Boost but still interactive -
> * Boost - classic Boost (no Java Script) -
different highlighting theme). This way the user could highlight using
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.