Proposal: Abandoning monolithic Boost documentation.
Today, in slack, we had a discussion on problems with building the monolithic docs. For context what I'm calling the monolithic docs are these <https://www.boost.org/doc/libs/1_88_0/doc/html/libraries.html>. The main problem that was raised is that a failure in one library causes all the docs to disappear. That problem is due to the nature of DocBook, XSLT, and the single monolithic generation. This is not something that can be resolved at the build system leve. The one solution is to abandon the monolithic build. And instead move to only having per library documentation builds. Hence.. I am proposing we abandon the monolithic documentation build. The benefits: * No longer missing docs from problems in individual libraries. * It's modular. I.e. libraries would build, and include, their docs in the modular layout. Do note that most libraries, more than 2/3, already use modular documentation. So technically this would be completing the modular transition that has already been happening. Thoughts? -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supongas Nada -- Robot Dreams - http://robot-dreams.net
I am proposing we abandon the monolithic> documentation build. Many times recently, I have feltthat the monolithic docs are outdated.In fact, it can be hard to find whatyou seek in them. Since we are on GitHub, in a perfect world,I would put terse (well, as terse as possible)docs for each individual library in markdown.These can be located in the Submodule's homepage. There is no longer any need at all toproduce code listings in the docs. Thisis wasted space. Christopher On Friday, April 18, 2025 at 06:54:22 PM GMT+2, René Ferdinand Rivera Morell via Boost <boost@lists.boost.org> wrote:
Today, in slack, we had a discussion on problems with building the monolithic docs. For context what I'm calling the monolithic docs are these <https://www.boost.org/doc/libs/1_88_0/doc/html/libraries.html>. The main problem that was raised is that a failure in one library causes all the docs to disappear. That problem is due to the nature of DocBook, XSLT, and the single monolithic generation. This is not something that can be resolved at the build system leve. The one solution is to abandon the monolithic build. And instead move to only having per library documentation builds. Hence.. I am proposing we abandon the monolithic documentation build. The benefits: * No longer missing docs from problems in individual libraries. * It's modular. I.e. libraries would build, and include, their docs in the modular layout. Do note that most libraries, more than 2/3, already use modular documentation. So technically this would be completing the modular transition that has already been happening. Thoughts? -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supongas Nada -- Robot Dreams - http://robot-dreams.net _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 18 Apr 2025 19:53, René Ferdinand Rivera Morell via Boost wrote:
Today, in slack, we had a discussion on problems with building the monolithic docs. For context what I'm calling the monolithic docs are these <https://www.boost.org/doc/libs/1_88_0/doc/html/libraries.html>. The main problem that was raised is that a failure in one library causes all the docs to disappear. That problem is due to the nature of DocBook, XSLT, and the single monolithic generation. This is not something that can be resolved at the build system leve. The one solution is to abandon the monolithic build. And instead move to only having per library documentation builds. Hence..
I am proposing we abandon the monolithic documentation build. The benefits:
* No longer missing docs from problems in individual libraries. * It's modular. I.e. libraries would build, and include, their docs in the modular layout.
Do note that most libraries, more than 2/3, already use modular documentation. So technically this would be completing the modular transition that has already been happening.
Thoughts?
I'm ok with this, but I think all of my libraries already use modular doc builds. I imagine, the majority of libraries that still build in the root doc directory are the old ones, probably not well maintained. Who's going to update those and is there a description of what needs to be done? I think, some changes to superproject were also required.
The main problem that was raised is that a failure in one library causes all the docs to disappear. No longer missing docs from problems in individual libraries.
There is a meaningful advantage to that "problem" though. Right now boostorg/pfr docs are failing. Peter and I commented to the author. This morning I submitted a bug fix which is just waiting to be merged. Imagine the alternative: a mostly-unmaintained library starts to have doc failures. The 'superproject' continues to build fine. Nobody sees the issue as particularly important. Perhaps someone notices, but think "it's that maintainer's responsibility". The next thing you know, it's time for a boost release and the library's docs will not be included in the official archive since they are not building. Which means, at minimum... set up persistent email notifications and show the build is failing somehow.
Sam Darwin wrote:
The main problem that was raised is that a failure in one library causes all the docs to disappear. No longer missing docs from problems in individual libraries.
There is a meaningful advantage to that "problem" though. Right now boostorg/pfr docs are failing. Peter and I commented to the author. This morning I submitted a bug fix which is just waiting to be merged. Imagine the alternative: a mostly-unmaintained library starts to have doc failures. The 'superproject' continues to build fine. Nobody sees the issue as particularly important. Perhaps someone notices, but think "it's that maintainer's responsibility". The next thing you know, it's time for a boost release and the library's docs will not be included in the official archive since they are not building.
This is an advantage when doing releases, but very much a disadvantage when one just wants to work on one's own docs and see the result on boost.org. Also, the failure notifications go to the wrong people (you and me), rather than to the maintainers. But that's probably unavoidable either way.
On 18 Apr 2025 20:31, Sam Darwin wrote:
The main problem that was raised is that a failure in one library causes all the docs to disappear. No longer missing docs from problems in individual libraries.
There is a meaningful advantage to that "problem" though. Right now boostorg/pfr docs are failing. Peter and I commented to the author. This morning I submitted a bug fix which is just waiting to be merged. Imagine the alternative: a mostly-unmaintained library starts to have doc failures. The 'superproject' continues to build fine. Nobody sees the issue as particularly important. Perhaps someone notices, but think "it's that maintainer's responsibility". The next thing you know, it's time for a boost release and the library's docs will not be included in the official archive since they are not building. Which means, at minimum... set up persistent email notifications and show the build is failing somehow.
Perhaps, the answer to that is setting up a per-library CI that builds the library docs. Though if the library is unmaintained, it wouldn't have much of an effect.
Perhaps, the answer to that is setting up a per-library CI that builds the library docs.
Could be. boostorg/release-tools has multiple such CI jobs already. Perhaps set a schedule there, on job that 'must' pass every time. However will the effect be the same as circleci... It should also should be marked as 'red' instead of 'green' from the exit code of the shell script.
Am 18.04.25 um 19:45 schrieb Andrey Semashev via Boost:
Perhaps, the answer to that is setting up a per-library CI that builds the library docs. Though if the library is unmaintained, it wouldn't have much of an effect.
I fully agree with that. The documentation build should be functional at each point in time and hence that should be tested in the same way as the rest of the code. I actually have that as part of CI for my libraries. E.g. https://github.com/boostorg/nowide/blob/f3566858722e0bb9fea057ea06078f112543... I guess for other libraries a similar job is easy enough to include. But then again: Who receives the notifications and can that person act on it to get it fixed?
At what point is a boost documentation considered modular? I'd like to avoid rewriting the docs for my libraries. 18.04.2025 18:54:23 René Ferdinand Rivera Morell via Boost <boost@lists.boost.org>:
Today, in slack, we had a discussion on problems with building the monolithic docs. For context what I'm calling the monolithic docs are these <https://www.boost.org/doc/libs/1_88_0/doc/html/libraries.html>. The main problem that was raised is that a failure in one library causes all the docs to disappear. That problem is due to the nature of DocBook, XSLT, and the single monolithic generation. This is not something that can be resolved at the build system leve. The one solution is to abandon the monolithic build. And instead move to only having per library documentation builds. Hence..
I am proposing we abandon the monolithic documentation build. The benefits:
* No longer missing docs from problems in individual libraries. * It's modular. I.e. libraries would build, and include, their docs in the modular layout.
Do note that most libraries, more than 2/3, already use modular documentation. So technically this would be completing the modular transition that has already been happening.
Thoughts?
-- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supongas Nada -- Robot Dreams - http://robot-dreams.net
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Fri, Apr 18, 2025 at 1:45 PM <oliver.kowalke@gmail.com> wrote:
At what point is a boost documentation considered modular? I'd like to avoid rewriting the docs for my libraries.
Same definition as I've used for other uses of "modular". When you can build the library docs with only the specific dependencies for building the docs are available. The ideal, of course, being only needing to have the doc building tools installed. I.e. avoiding needing boost-root and the boost-root structure is ideal. IMO. -- -- René Ferdinand Rivera Morell -- Don't Assume Anything -- No Supongas Nada -- Robot Dreams - http://robot-dreams.net
пт, 18 апр. 2025 г. в 21:46, oliver.kowalke--- via Boost <boost@lists.boost.org>:
At what point is a boost documentation considered modular? I'd like to avoid rewriting the docs for my libraries.
Libraries that have monolithic documentation are listed on this page. https://www.boost.org/doc/libs/1_88_0/doc/html/index.html BTW, I volunteer to help switching docs from the monolithic to "modular" approach. I can also volunteer to help transitioning docs to Asciidoctor, if the library author wants that, or if the library is unmaintained.
On 4/18/25 12:00 PM, Дмитрий Архипов via Boost wrote:
пт, 18 апр. 2025 г. в 21:46, oliver.kowalke--- via Boost <boost@lists.boost.org>:
At what point is a boost documentation considered modular? I'd like to avoid rewriting the docs for my libraries.
Libraries that have monolithic documentation are listed on this page.
https://www.boost.org/doc/libs/1_88_0/doc/html/index.html
BTW, I volunteer to help switching docs from the monolithic to "modular" approach. I can also volunteer to help transitioning docs to Asciidoctor, if the library author wants that, or if the library is unmaintained.
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
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. Robert Ramey
вт, 22 апр. 2025 г. в 22:26, Robert Ramey via Boost <boost@lists.boost.org>:
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. 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. 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. 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).
On 22 Apr 2025 22:50, Дмитрий Архипов via Boost wrote:
вт, 22 апр. 2025 г. в 22:26, Robert Ramey via Boost <boost@lists.boost.org>:
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. 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.
I don't think anyone suggested storing (in git) the generated html. I know some libraries do that, but maintainers of those libraries have taken the responsibility to keep the source and generated content in sync. Whether the docs are modularized or not is orthogonal to that. I think, what Robert suggested is to just build the monolithic docs from modularized. As far as html goes, nothing needs to be done as we already list all libraries on the website, whether they use modularized or centralized docs. For pdf, I don't think it would be easy or at all possible to generate a single pdf from multiple libraries. Though I doubt there is any demand for that nowdays.
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. This is because that contributor would still have to get the necessary tool.
This also doesn't change with this proposal. If anything, it has the potential to increase the tool diversity.
On 4/22/25 2:30 PM, Andrey Semashev via Boost wrote:
I don't think anyone suggested storing (in git) the generated html. My libraries do that. Basically it so anyone who download the git repo as a zip file (E.G. a user) can read the documentation right away and know that it is in sync with the code.
I know some libraries do that, but maintainers of those libraries have taken the responsibility to keep the source and generated content in sync.
That's what I have done. Never had a complaint about it.
Whether the docs are modularized or not is orthogonal to that.
I think, what Robert suggested is to just build the monolithic docs from modularized. As far as html goes, nothing needs to be done as we already list all libraries on the website, whether they use modularized or centralized docs.
To be honest, I've been having difficulty understanding the monolithic vs modularized discussion. Every time I think I understand it, I come across some post which confuses me again. <off topic> Truth is I've never understood what the "release" process is. This is after 20+ years as a Boost developer. I had always assumed it just giant zip file with all the libs and toos which one installs on his machine and then follows the "getting started" section of Boost documentation. Make of this what you will </off topic>
For pdf, I don't think it would be easy or at all possible to generate a single pdf from multiple libraries. Though I doubt there is any demand for that nowdays.
I talked to some users at a conference maybe 15 years ago. The expressed great affection for the pdf version of the docs. I also very much like pdf for other non-boost projects I work on. So I've always been a fan (maybe the last one) of BoostBook. If everyone used BoostBook we could generate a giant Boost reference with index, table of contents etc. Sounded cool at the time, but given the current size of boost it's utility would likely be limited. However having one "book" per library and a cross reference would be pretty cool if I didn't have to build it and it just came along with the down load like html does (in my world).
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. This is because that contributor would still have to get the necessary tool.
Right. In my world the download for each library would contain both the html and the original document source. Most have no interest in the document source, they just want to read the documentation so the use the library RIGHT NOW (users are very impatient) preferable without having to go to the web.
This also doesn't change with this proposal. If anything, it has the potential to increase the tool diversity.
We've always had the view that the canonical form of documentation is html. Thus, the tool the any individual developer chooses to use is totally up to him. One can argue that this view is/has been misguided, but it has the advantage that developers across all time and space don't have to agree on a documentation build toolset. Robert Ramey
For pdf, I don't think it would be easy or at all possible to generate a single pdf from multiple libraries. Though I doubt there is any demand for that nowdays.
I talked to some users at a conference maybe 15 years ago. The expressed great affection for the pdf version of the docs. I also very much like pdf for other non-boost projects I work on.
As the person who used to generate those PDF's, I can tall you it was a right pain to do, plus there seemed to be very few downloads... that might be a chicken and egg situation though. If it was all automated and run on CI that might make it viable again I guess. And yes, by all means modularize the docs, I don't think there were ever that many libraries in the old "monolithic" build anyway? John.
ср, 23 апр. 2025 г. в 12:01, John Maddock via Boost <boost@lists.boost.org>:
As the person who used to generate those PDF's, I can tall you it was a right pain to do, plus there seemed to be very few downloads... that might be a chicken and egg situation though. If it was all automated and run on CI that might make it viable again I guess.
And yes, by all means modularize the docs, I don't think there were ever that many libraries in the old "monolithic" build anyway?
I recently collected some info on the docs setups for Boost libraries: https://disk.yandex.ru/i/f4fRfsZFOqX4TA 45 libraries (out of 152) use integrated docs. 4 of those actually don't even use Quickbook, their docs are written in BoostBook XML! 120 libraries' docs can be built as PDFs, of those 92 have explicit considerations for PDF format (which implies their maintainers at one point cared enough about PDF). 4 libraries have pre-generated docs with PDF, that is they have PDF files committed.
Дмитрий Архипов:
ср, 23 апр. 2025 г. в 12:01, John Maddock via Boost <boost@lists.boost.org>:
As the person who used to generate those PDF's, I can tall you it was a right pain to do, plus there seemed to be very few downloads... that might be a chicken and egg situation though. If it was all automated and run on CI that might make it viable again I guess.
And yes, by all means modularize the docs, I don't think there were ever that many libraries in the old "monolithic" build anyway?
I recently collected some info on the docs setups for Boost libraries: https://disk.yandex.ru/i/f4fRfsZFOqX4TA
45 libraries (out of 152) use integrated docs. 4 of those actually don't even use Quickbook, their docs are written in BoostBook XML! 120 libraries' docs can be built as PDFs, of those 92 have explicit considerations for PDF format (which implies their maintainers at one point cared enough about PDF). 4 libraries have pre-generated docs with PDF, that is they have PDF files committed.
Asciidoctor single page may not be especially liked, but it does work as a PDF. I'm not sure anyone uses this though, even though I try to make sure it works.
On 23/04/2025 10:19, Дмитрий Архипов via Boost wrote:
ср, 23 апр. 2025 г. в 12:01, John Maddock via Boost <boost@lists.boost.org>:
As the person who used to generate those PDF's, I can tall you it was a right pain to do, plus there seemed to be very few downloads... that might be a chicken and egg situation though. If it was all automated and run on CI that might make it viable again I guess.
And yes, by all means modularize the docs, I don't think there were ever that many libraries in the old "monolithic" build anyway? I recently collected some info on the docs setups for Boost libraries: https://disk.yandex.ru/i/f4fRfsZFOqX4TA
45 libraries (out of 152) use integrated docs. 4 of those actually don't even use Quickbook, their docs are written in BoostBook XML! 120 libraries' docs can be built as PDFs, of those 92 have explicit considerations for PDF format (which implies their maintainers at one point cared enough about PDF).
Those PDF considerations were probably all added by me when I did care about PDF's. ;) John.
Am 23.04.25 um 05:24 schrieb Robert Ramey via Boost:
On 4/22/25 2:30 PM, Andrey Semashev via Boost wrote:
I don't think anyone suggested storing (in git) the generated html. My libraries do that. Basically it so anyone who download the git repo as a zip file (E.G. a user) can read the documentation right away and know that it is in sync with the code.
I don't agree with the last part: If the built documentation (HTML/PDF) is in the repo I cannot "know" if it is up to date as I don't know how often it is regenerated from its prime source. E.g. if it contains code snippets taken from the actual source code and that has changed without remembering that it is referenced, and hence requires doc regeneration, the documentation will be outdated. As Дмитрий Архипов just noted: People make mistakes and forget stuff. Or contributors get confused if there are only HTML pages or they need to update something else. To put it a bit blunt: The only safe way to ensure the (built) documentation is not outdated is to not have them in regular sources. On fixed points in time it should be (re)generated and distributed with the sources at that point in time, i.e. releases. Of course those mistakes with forgotten updates when keeping the generated artifacts in the repo can be mitigated by a CI check that e.g. generates the sources and fails if there are differences. This also has the advantage of contributors being able to do that in PRs touching documentation.
ср, 23 апр. 2025 г. в 12:25, Alexander Grund via Boost <boost@lists.boost.org>:
Of course those mistakes with forgotten updates when keeping the generated artifacts in the repo can be mitigated by a CI check that e.g. generates the sources and fails if there are differences. This also has the advantage of contributors being able to do that in PRs touching documentation.
BTW, Sam Darwin has set up docs preview for PRs for some of the Boost libs. I am currently working on a significant change to JSON's documentation and the preview is very handy. I also can share links to it with people, e.g. compare https://1080.json.prtest2.cppalliance.org/libs/json/doc/html/ref/array/array... with https://www.boost.org/doc/libs/develop/libs/json/doc/html/json/ref/boost__js...
On 4/22/25 12:50 PM, Дмитрий Архипов via Boost wrote:
вт, 22 апр. 2025 г. в 22:26, Robert Ramey via Boost <boost@lists.boost.org>:
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
ср, 23 апр. 2025 г. в 06:08, Robert Ramey via Boost <boost@lists.boost.org>:
Right. But people shouldn't do that. ... Right. But people shouldn't do that. Same as above.
Right, people shouldn't make mistakes. Silly them.
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.
I take it you've never had contributors that actually changed the documentation themselves. I have. For those people it would be useful to be able to regenerate the docs locally. BTW, I have a suspicion that you don't have many contributors willing to fix docs, because IIRC you generate your docs using a proprietary program that is installed on your computer. ср, 23 апр. 2025 г. в 06:24, Robert Ramey via Boost <boost@lists.boost.org>:
My libraries do that. Basically it so anyone who download the git repo as a zip file (E.G. a user) can read the documentation right away and know that it is in sync with the code.
This may blow your mind, but a user can do that even without downloading the git repo as a zip file: https://www.boost.org/doc/libs/develop/
To be honest, I've been having difficulty understanding the monolithic vs modularized discussion. Every time I think I understand it, I come across some post which confuses me again.
Here we discuss building documentation for several projects as a single entity, as opposed to building them as separate entities. Maybe it would be better to call it integrated vs. standalone documentation so that we don't mix this with modular library projects. The benefit of removing integrated builds is slightly simplified docs build process (for release) and docs build scripts (for all libraries).
I talked to some users at a conference maybe 15 years ago. The expressed great affection for the pdf version of the docs. I also very much like pdf for other non-boost projects I work on.
Can you share some thoughts on the benefits of PDFs? I find them inferior to HTML in every regard when reading from a computer (or a phone) screen. And printing docs is a fictional thing invented by Fred Brooks for Mythical Man-Month.
Right. In my world the download for each library would contain both the html and the original document source. Most have no interest in the document source, they just want to read the documentation so the use the library RIGHT NOW (users are very impatient) preferable without having to go to the web.
Who are those users who have an aversion to going to the web? How do they get your project's sources without going to the web? Do they have a short window where they have Internet access, like they are on an exoplanet? I have relatives that live in a village in taiga. They don't have indoor plumbing, but they have good enough Internet access to send GIFs daily.
On 23 Apr 2025 12:04, Дмитрий Архипов via Boost wrote:
Right. In my world the download for each library would contain both the html and the original document source. Most have no interest in the document source, they just want to read the documentation so the use the library RIGHT NOW (users are very impatient) preferable without having to go to the web.
Who are those users who have an aversion to going to the web? How do they get your project's sources without going to the web? Do they have a short window where they have Internet access, like they are on an exoplanet? I have relatives that live in a village in taiga. They don't have indoor plumbing, but they have good enough Internet access to send GIFs daily.
To be fair, offline docs are useful for packaging. And I mean truly offline, i.e. when the built html contains no references to online resources that are needed to view them, especially no online tracking stuff. E.g. on Debian, you can install libboost-doc and have all of the Boost documentation locally. This can be used in closed environments, where Internet access is restricted. (I know because I've been in such environment, although last time it was many years ago.) Some people are also concerned with privacy. So yes, offline html docs is a thing, but it doesn't necessarily mean they should be committed in git. They should simply be available somewhere to anyone who needs them. A downloadable tarball works fine.
On 4/23/25 2:04 AM, Дмитрий Архипов via Boost wrote:
ср, 23 апр. 2025 г. в 06:08, Robert Ramey via Boost <boost@lists.boost.org>:
Right. But people shouldn't do that. ... Right. But people shouldn't do that. Same as above.
Right, people shouldn't make mistakes. Silly them.
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.
I take it you've never had contributors that actually changed the documentation themselves. I have. For those people it would be useful to be able to regenerate the docs locally.
1) With few acceptions I find it unacceptable that a "contributor" directly change any files in a library that I maintain. Such changes should be in PRs. Then as maintainer I can merge them or not. If the PR contains a documentation change in the html, I can hand transfer it to the documentation source and regenerate the html - which I do from time to time. In my case, all html documents on the master branch are always in sync with the documentation source. And the documentation source on the master branch is always in sync with the code - unless I've made a mistake - which happens occasionally.
BTW, I have a suspicion that you don't have many contributors willing to fix docs, because IIRC you generate your docs using a proprietary program that is installed on your computer.
I don't know how "contributors" (I'm not sure whom you're referring to) generally don't have access to files in the library. And if they did, I would not expect them to necessarily have access to the documentaion generation tool or have interest in learning out to use it.
This may blow your mind, but a user can do that even without downloading the git repo as a zip file: https://www.boost.org/doc/libs/develop/
I'm aware of this. This may blow your mind, but I'm not always connected to the net. And the version of the docs/library I find there might be identical to the one I downloaded. I like having a complete known consistent package which constitutes the library. If I use the library, I like knowing that it will be useful for decades - long after Boost might itself might have disappeared. This is a common requirement in some environments.
To be honest, I've been having difficulty understanding the monolithic vs modularized discussion. Every time I think I understand it, I come across some post which confuses me again.
Here we discuss building documentation for several projects as a single entity, as opposed to building them as separate entities. Maybe it would be better to call it integrated vs. standalone documentation so that we don't mix this with modular library projects. The benefit of removing integrated builds is slightly simplified docs build process (for release) and docs build scripts (for all libraries).
One thing I'm not getting is how one does an "integrated documentation" build when there's no guarentee that everyone uses the same tool to do so. At one time, it was "mandated" that Boost Book be used - but that was relaxed so each developer could indulge his creative genius and here we are.
I talked to some users at a conference maybe 15 years ago. The expressed great affection for the pdf version of the docs. I also very much like pdf for other non-boost projects I work on.
Can you share some thoughts on the benefits of PDFs? I find them inferior to HTML in every regard when reading from a computer (or a phone) screen. And printing docs is a fictional thing invented by Fred Brooks for Mythical Man-Month.
I'm not advocating for pdfs specifically. And I agree that they are much less popular than they used to be. My personal preference these days is for Boost Book (or DocBook). I edit this with an XML editor (XMLMind) and generate the html with BoostBook toolchain. As a free bonus it generates pdf as well - though it probably wouldn't be missed. Truth is, I'm sort of sucker for free stuff. I do like that BoostBook has the capability of generating format for which there exists and xslt tranform for - though to be honest, I've only used it for pdf.
Right. In my world the download for each library would contain both the html and the original document source. Most have no interest in the document source, they just want to read the documentation so the use the library RIGHT NOW (users are very impatient) preferable without having to go to the web.
Who are those users who have an aversion to going to the web?
I am one of those users.
How do they get your project's sources without going to the web? Do they have a short window where they have Internet access, like they are on an exoplanet? I have relatives that live in a village in taiga. They don't have indoor plumbing, but they have good enough Internet access to send GIFs daily.
LOL - perhaps the world has lost it's way Robert Ramey
integrated vs. standalone documentation
There are multiple levels of "integrated vs. standalone vs. modules." Some boost docs are built within the superproject and the html goes into the top-level boost doc/ folder. More modular docs output their own set of html into libs/_my_lib_/docs.
how one does an "integrated documentation"
The general idea is that for separate modular docs (which is preferred), all you need to do is check out that particular library repository and build those. However "integrated documentation" is more complicated, it involves all the libraries, and many toolsets. Run https://github.com/boostorg/release-tools scripts in a container. Instructions: https://github.com/boostorg/release-tools/blob/develop/docs/README.md However, since this is automated and the results are published each day: https://www.boost.org/doc/libs/develop/ it's not necessary for a user to build in that way.
participants (10)
-
Alexander Grund -
Andrey Semashev -
Christopher Kormanyos -
John Maddock -
oliver.kowalke＠gmail.com -
Peter Dimov -
René Ferdinand Rivera Morell -
Robert Ramey -
Sam Darwin -
Дмитрий Архипов