Re: [Boost-docs] [poly_collection] Doc not being automatically built

Subject: Re: [Boost-docs] [poly_collection] Doc not being automatically built
From: Joaquin M López Muñoz (joaquinlopezmunoz_at_[hidden])
Date: 2017-06-08 08:59:53

El 08/06/2017 a las 4:28, Daniel James via Boost-docs escribió:
> FWIW I started writing some documentation on building documentation here:
> http://boostorg.github.io/quickbook/doc/html/boost_doc_tools/boost_build.html
>
> Although I don't understand the build system that well, I never
> managed to finish it, and it's out of date now as it doesn't include
> any details on how to integrate with the new setup (the boostrelease
> and boostdoc targets). It also wouldn't have answered any of your
> questions, even if I had finished it. Writing this stuff always feels
> futile, so I find it hard to be motivated enough to do it. In the end,
> it's considerably less work to just answer questions and help solve
> people's problems than write and maintain documentation that most
> never bother to read.

Thinking out loud here: a thing that might help without too much 
documenting effort
woud be a set of templates for BoostBook/Quickbook jamfiles that people 
can rip and
use for their own libs. As it happens, the final jamfiles are subtle to 
write but not
excessively verbose. For instance, the following

https://github.com/boostorg/poly_collection/blob/develop/doc/Jamfile.v2

can be adapted to any lib by s/poly_collection/lib_name under these 
assumptions:

   * doc is written in lib_name.qbk
   * author wants to generate standalone and boostdoc builds
   * images are stored (pre-build) in lib_name/doc/img and are referenced as
     [$lib_name/img/whatever.png] in the Quickbook doc
   * images include a boost.png logo for the standalone build

and that's it. Surely this requirements sheet fits many people without 
special needs,
and we're sparing them the need to understand the details of the process.

Another example: the following took me days and dozens of attempts to 
get right:

https://github.com/boostorg/poly_collection/blob/develop/.travis.yml

but the result is usable for any lib with s/poly_collection/lib_name 
under the
following requirements:

  * GCC 5.2, Clang 3.7
  * C++11

Admittedly, Travis CI is not part of the official Boost build tools, but 
you get the idea.
Maybe a reduced numbers of templates (not more than 10) can serve 90% of
authors. If you're like me and a template can be used off-the-shelf, you 
really don't
want to know anything more about the intricacies of the processes involved.

Joaquín M López Muñoz