Subject: Re: [boost] ATTENTION: Library requirements..
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2016-01-08 05:35:08
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.
>
> Now that we're on git, and each library's repository already has two
> branches (master,d develop), maybe it would be a good idea to institute (as
> policy) or support (in our infrastructure) a third branch for
> documentation.
I think this design is broken: which code branch would this
documentation branch refers to? documentation is related to code, this
is why it is currently part of the repository and versioned in the same way.
>
> 1. It serves the users who want to easily view documentation for a given
> library's repository. (They can clone that documentation branch).
The documentation that the user is viewing is (most of the time)
generated. Cloning that would not help the user contributing to it.
There is a mechanism though with gihub that serves static pages:
if you fork the library, and create a gh-page branch on your fork, you
benefit from a webserver automatically:
https://help.github.com/categories/github-pages-basics/ . If you put
your generated documentation there, maybe with an appropriate front page
indicating the revision, this would help.
I believe it is useful for intermediate state or reviews: you want to
communicate some new design to the ML and point to your fork static
pages, without interfering with the boost.org content. But I do believe
that for the long run, this intermediate state should be removed as soon
as integrated to one of the main branches master/develop.
> 2. It doesn't require us to put generated documentation output in our main
> development branches.
> 3. It might even allow you support things like: "If <library> has 'docs'
> branch, don't require it to have a root level index.html."
Well... I still do not know what this index.html is for, so I am leaving
it there :)
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.
Best,
Raffi