Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2016-01-09 18:56:20

On Sat, Jan 9, 2016 at 8:23 AM, Raffi Enficiaud <
raffi.enficiaud_at_[hidden]> wrote:
>
> Le 08/01/16 17:39, Rene Rivera a écrit :
>>
>> On Fri, Jan 8, 2016 at 4:35 AM, Raffi Enficiaud <
>> raffi.enficiaud_at_[hidden]> wrote:
>>
>>> 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.
>
>
> Sorry, I cannot find the piece of information. While you (certainly) can
provide a good answer for predef, the question remains: would this practice
of committing generated files be the recommended way?

<http://lists.boost.org/Archives/boost/2016/01/227127.php>

It goes something like this..

1. A library is required to have HTML documentation.
2. A library *can* integrate into the global Boost documentation.
3. If a library doesn't do #2 it *must* provide prebuilt HTML documentation.

Hence, even though Predef uses quickbook, it's never done #2. Therefore
Predef does #3 :-)

>>
>> [snip]
>>
>>> 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:
>
>
> Well, you (I have the feeling that you support this burden alone... )

Not entirely alone. Daniel does most of the website and documentation
support. And I do most of the automation and testing support. And a few
other people, like John and Marshal, do other stuff. But we all overlap to
some extent.

> are facing a problem for maintaining the infrastructure. Wouldn't it be
the right time for restricting the toolset available to developers?

Perhaps. But in the past that's been a considerable argument when that
subject comes up :-)

> or if developers want to do something fancy, they need to contribute to
the generation toochain as well? As such, contributing to your travis.yml
(or a Dockerfile for setting up the environment) would be beneficial. After
all, code development, IT related stuff, etc, are all in the same boat.

Indeed.

> OTOH, you are proposing a common interface for generating the different
artifacts of the build (binaries, test results, doc...). If only one
library needs some special care and departs from that interface, I believe
those commands can be integrated in the Jamfile directly with some black
magic. The only thing that is impacted is the surrounding environment in
which it is generated.

Right. What I want is a single way that the tools can reliably build. And
leave it up to authors to implement what they want from there. I.e. a build
jamfile, and some specified results (html docs for example). Where that
falls apart is on the requirements that the libs want for doing their
builds. For example, for Geometry we need to download RapidXML to even
build the custom documentation tool it uses, even before getting to use the
regular quickbook/boostbook chain.

>> 1. It's failing to build ptr_container docs. See log <
>> https://s3.amazonaws.com/archive.travis-ci.org/jobs/100985614/log.txt>.
>
>
> The coupling here between libraries seems to be problematic as well (and
also the coupling between doc, test, etc). To me, your are hitting the same
problem as the discussions we already had concerning the regression tests
(but this is obviously another topic).
>
>> 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.
>
>
> I do not know bintray, it certainly does provide a lot of services. But I
have the feeling that we "only" need a place to store files and make them
available through a web server (along maybe with their revision, branch
etc). I should be missing something in thinking that bintray is overkill.

It's convenient in the minimal setup on my end involved (just setting up
the account and doing web POST requests). And the end result is reasonable.

> We can continue this topic offline or in the test or build ML if you want.

Sure.

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