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
> > On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart <rob.s...@
> > wrote:
> > > 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
> > 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
> > > run sample code shown in the docs. If the sample program was somehow
> > > interactive or the code was editable such that one could experiment
> > > 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
> > 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
> > 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
> > mind.
> > 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
> > 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/
> > 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
> >the docs can be built by setting the theme to `boost` either on the
> >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
> Script magic.
> Moreover, I have removed a lot of not needed files from the theme. When
> look and feel
> of the spec will be approved by the boost users I will create a pull
> so that you can
> check what I have changed. Thanks again for a great job on the
Ah yes, tables is something that needs improving. I was working with the
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.
documentation source directory, plus additional files can be included using
this yet(I haven't had a need for it yet), but it should be supported.
official approval in boost.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk