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-24 13:16:40

>
> > If there is an interest I can provide generic solution to allow 
> developers 
> > to write documentation 
> > using markdown (mkdocs) and simply integrate it with their libraries. 
> > Currently, theme is just slightly modified version of readthedocs, 
> however 
> > Paul Fultz II has prepared a boost theme for Fit library ( 
> > https://github.com/pfultz2/mkdocs-boost) already and it might be easily 
> > integration with the JS facilities provided. 
>
> But this is totally the wrong way to go about this.  We have a 
> documentation infrastructure which, for the most part, works quite well. 
>   I produces relatively high quality linked presentation which is 
> consistent accross those boost library (the majority) which use it. 
>

Boost documentation infrastructure works quite well with much weeping and
gnashing of teeth. With mkdocs, its easy for users to generate the
documentation and it integrates with other tools(the documentation is
regenerated on push at readthedocs.org).
 

>
> I'm very familiar wiht Paul Fultz TICK library documentation and found 
> it to be unworthy of the underlying package.  Most of the problem is the 
> text, reference, lack of examples, weak tutorial etc.  But the 
> presentation as a web page is quite different that the boost libraries. 
> It's jaring and not as effective.  There is also - as far as know anyway 
> to produce a PDF version of the documentation.  This last is something 
> the Boost Documentation system can do - albiet reserved for those who 
> prefer to do their own dentistry. 
>

The Tick library is "unworthy" of a formal review currently, and the
documentation is lacking because I have been working on preparing the
Boost.Fit library for formal review(which starts next week). You can see the
documentation for Boost.Fit here:

http://pfultz2.github.io/Fit/doc/html/

It is much more complete with the boost look and feel, while being generated
using the same "underlying package" that both Boost.Tick and Boost.DI uses.

Also a PDF can be generated using `mkdocs2pandoc` tool.

Paul