Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2016-01-08 11:39:13

On Fri, Jan 8, 2016 at 4:35 AM, Raffi Enficiaud <
raffi.enficiaud_at_[hidden]> wrote:

> Le 07/01/16 19:30, Glen Fernandes a écrit :
>
>> Rene wrote:
>>
>>> I'm making my Predef library be that "golden" example. By commenting the
>>> source to illustrate the requirements. But since my lib doesn't have
>>> source
>>> it may not be the best.
>>>
>>
>> It's interesting that Boost.Predef has both QBK sources and generated HTML
>> output in the repository. I was considering doing this for Boost.Align but
>> did not want repository history affected by commits around generation of
>> documentation.
>>
>
> My 2cents...
>
> I believe anything that can be generated automatically (and that is
> currently part of the release toolchain) should be deleted from the
> repositories.

See my previous reply as to why both are there for Predef.

> Well... I still do not know what this index.html is for, so I am leaving
> it there :)
>

It's explained in the requirements doc we are discussing "Authors have
requested this so that they can publish URL's in the form
http://www.boost.org/libs/lib-name with the assurance a documentation
reorganization won't invalidate the URL.".

>
> One thing I would like to point concerning documentation is:
> - we have all the machinery on the develop and master branches to see the
> generated documentation: it is 0 effort from the developers to see the
> documentation as it would be shipped (no need to generate or
> commit/maintain generated file)
> - however the frequency of the updates is very low, sometimes once a
> month: I believe this should be done much more frequently, something like
> daily by one dedicated runner.
>

Part of the requirement changes is to do just that. As right now that
machinery is complicated because of the toolchain setup and, in one case,
hand written instructions to follow for building library docs. But do not
despair, I'm working on it. And the current Travis-CI is set up to build
docs for all libraries on every root update. This is part of supporting
continuous building of release level archives. Unfortunately that currently
has two problems:

1. It's failing to build ptr_container docs. See log <
https://s3.amazonaws.com/archive.travis-ci.org/jobs/100985614/log.txt>.

2. We don't have a place to reliably upload non-master archives. Currently
it's set up to upload to bintray.com on the master branch only. As doing
the uploads on develop got us throttled for uploading too much. So if
someone has a suggestion that is equivalent to bintray I would love to know
about it.

-- 
-- Rene Rivera
-- Grafik - Don't Assume Anything
-- Robot Dreams - http://robot-dreams.net
-- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail