Re: Question regarding Boost Documentation

From: Robert Ramey (ramey_at_[hidden])
Date: 2024-08-10 14:07:26

On 8/10/24 2:42 AM, Peter Dimov via Boost wrote:
> Robert Ramey wrote:
>>   From the point of view of modularization, wouldn't it make more sense
>> just to generated inside the libraries doc/html directory?  FWIW, I
>> generate for my own libraries and check them into the git repo.  I know
>> this might seem redundant, but it relieves the user and or release of
>> building the docs and permits the documentation to be browsed on one's
>> local environment.
> 
> The downsides of checking in generated files (build output artifacts) are
> well known.
> 
a) > E.g. a pull request modifying the doc/html files will get 
overwritten by
> the next build,

I'm not sure I get this. One will always have the latest versions of 
documentation source and files checked in. I don't see a problem here.

> b) a pull request modifying just the source files won't
> be reflected in doc/html until the next rebuild,

Right.  One has to rebuild the docs locally and check in the updated 
files.  But it's limited to one library at a time and only invoked when 
documentation source changes.  It also fixes respectability on the 
person making the update.  So I would hope that occasional problems 
would would be addressed more expediently.

> c) and a pull request
> correctly modifying both sources and generated doc/html files may
> lead to lots of spurious changes to doc/html stemming from differences
> in the build environment (different tool versions etc).

I think I've noticed this and it IS annoying.  What I notice is that 
often the generated documentation has tags, indices etc which get 
regenerated and modified and I would call spurious changes. It's cost of 
doing business.

I see value having all the documentation for a library (source and 
files) in one place which moves around with the source code and is 
always available and in sync with with the library source.  Compare this 
to the current system.

Robert Ramey
> 
> 
> 
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
>