On 7/21/2014 9:21 AM, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Edward Diener Sent: 21 July 2014 14:13 To: boost@lists.boost.org Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
On 7/21/2014 7:02 AM, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Robert Ramey Sent: 20 July 2014 17:59 To: boost@lists.boost.org Subject: Re: [boost] [Boost Library Incubator] Unable to submit library
Edward Diener-3 wrote
On 7/20/2014 2:03 AM, Robert Ramey wrote:
Edward Diener-3 wrote
I think you can appreciate that having to duplicate tests which already exist through bjam/Boost Build when the user clones the project is not something I really want to do. I really don't see the big deal of someone interested in my library cloning it locally under modular-boost and then having all the documentation and tests
locally.
I explain very carefully in my top-level *.txt files how to do all this.
There's no disagreement here. That's exactly how I envision that this site be used.
I do appreciate the work you put into it. But I think that anyone interested in a library in the Boost Library Incubator sight should be trying it out locally just like everyone does with Git projects.
There's no disagreement here either.
But there are a couple issues you've left unaddressed.
a) One looking for a library can only find documentation for libraries already in boost. For the sandbox one had to download the package and (maybe) build the documentation in order to see the decimation. For me this was a big problem which I addressed by requiring browsable html documentation. The github method - (has a minor/temporary problem - I know) is perfect for this. It means one can browse the documentation immediately. So this issue is resolved for me.
The issue of generated (mainly html) files in GIT is still a nuisance.
If you are a sole developer, then it is quite easy - you simply include all the /doc folder with /html etc in GIT.
But if you are developing *with* someone else, these generated files are a PITA.
You have keep reverting the /html files every time you want to GIT pull.
And you have push the updated docs every time too - and these may be quite big.
I don't see a better way round this yet. Ideas?
I do not think that generated HTML documentation should be in Git. The only reason I put it in for my VMD library is because it is on the Boost review queue, so I am trying to make it easy for someone who might be interested in the library to look at the documentation without having to create it themselves. But really, with the proper jamfile in the docs directory, anybody should be able to recreate the docs.
While I think it is an advantage of the Boost Library Incubator that someone should be able to see the docs directly from the website, anyone interested enough in a library should be willing to clone it locally and regenerate the docs.
Historically, building the docs has been a step too far for most people.
Unless the build process can be fully automated, it's just not going to happen - not just to peruse a library that may never make it.
You have made a good point, but the principle remains the same: generated information which can easily change when some "source" changes is a PITA for any source control system.
I think that until we have fully digested modular-GIT, that's not going to happen either.
For Boost libraries does anybody put their generated documentation on Git ? I know that I don't for TTI.