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