On Fri, Jan 8, 2016 at 4:35 AM, Raffi Enficiaud < raffi.enficiaud@mines-paris.org> 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