Re: Proposal: Abandoning monolithic Boost documentation.

From: Robert Ramey (ramey_at_[hidden])
Date: 2025-04-23 03:08:09

On 4/22/25 12:50 PM, Дмитрий Архипов via Boost wrote:
> вт, 22 апр. 2025 г. в 22:26, Robert Ramey via Boost <boost_at_[hidden]>:
>>
>> Each library will have its html files to document it.  Would it not be
>> possible to write one (fancy) javascript to generate the the page above
>> just by scanning all the released libraries html?
>>
>> Then we'd have everything we have now without any depencies outside any
>> library. Looks practical to me.
> 
> The problem with storing generated HTML files in the project has
> already been mentioned multiple times:

> people regularly forget to
> update those HTML files when they change documentation. 

Right.  But people shouldn't do that.  We can't hope to anticipate and
compensate for all the bad things that people might do.  I don't know 
that this has been a problem for me.  I've just remembered to regenerate 
the HTML when ever I change the document source.  And just so you know, 
my memory was never much good and it's getting worse.

> There's an
> even worse problem when someone updates a HTML file, but not the
> source file, and the changes are lost on the next regeneration.

Right.  But people shouldn't do that. Same as above.

> And it doesn't solve the main problem with having multiple
> documentation formats in the project: that a contributor will have a
> hard time figuring out how to build docs for the library he is
> interested in. 

Hmmm ... I'm not understanding this.  A contributor makes and issue 
describing a problem with the documentation.  The maintainer updates the 
documentation to fix the issue.  Presumable the maintainer knows how to 
change the documentation source and regenerate the html.

> This is because that contributor would still have to
> get the necessary tool. With docs generated in CI, at least what are
> those tools and how to get them is written somewhere (build scripts,
> CI scripts, Dockerfiles).

This sounds like an argument for distributing the pre-built html. With 
the current system, I go to a library in git and it has no html.  I have 
to figure out how to generate it - which I won't spend time doing.  So 
only html is useful to me as a user/contributor.

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