AMDG On 8/7/24 17:29, Vinnie Falco via Boost wrote:

On Wed, Aug 7, 2024 at 3:45 PM Glen Fernandes via Boost < boost@lists.boost.org> wrote:

...

Are you referring to this: https://www.boost.org/doc/libs/1_85_0/doc/html/libraries.html

Please add Boost.Histogram to the global documentation or tell me why it is left out.

That list is not a complete index of boost documentation and is not all that useful. It's really only produced as an artifact of creating a single giant docbook document for many libraries. Boost.Histogram has its documentation built separately. In Christ, Steven Watanabe

On 8/7/24 3:45 PM, Glen Fernandes via Boost wrote:

On Wed, Aug 7, 2024 at 6:30 PM Robert Ramey via Boost wrote:

...

I think I recall that from time to time I see reference to a "global" (my term) documentation build which builds an html tree of all the boost libraries whose documentation has been built with boostbook. But in perusing the website I don't find any such documentation. What am I missing here?

Are you referring to this: https://www.boost.org/doc/libs/1_85_0/doc/html/libraries.html

That's it! Thanks. A couple more questions: a) how do I find this by navigating the boost website? I couldn't do and still can't figure this out even knowing that it's there. b) I notice that the Safe Numerics library isn't there. It doesn't use quickbook, but it DOES use boostbook. So I would expect to find it here. Robert Ramey

Glen

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

On 8/7/24 4:43 PM, Steven Watanabe via Boost wrote:

AMDG

On 8/7/24 17:35, Robert Ramey via Boost wrote:

...

a) how do I find this by navigating the boost website?  I couldn't do and still can't figure this out even knowing that it's there.

You don't (I suppose you could navigate up from the library pages). Why do you want to? The categorized index in libs/libraries.htm is better for any purpose I know of.

...

b) I notice that the Safe Numerics library isn't there.  It doesn't use quickbook, but it DOES use boostbook.  So I would expect to find it here.

Some libraries build their documentation in lib/xxx/doc/html, instead of using the global build.

I've always done that for my libraries so that one could read the documentation before downloading the library. A really dumb question. If the consolidated documentation is not available through the web site, what is the point of generating it. I'm sure it takes a lot of time. 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. Robert Ramey

In Christ, Steven Watanabe

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

On 8/7/24 9:07 PM, René Ferdinand Rivera Morell via Boost wrote:

On Wed, Aug 7, 2024 at 10:48 PM Robert Ramey via Boost wrote:

...

A really dumb question. If the consolidated documentation is not available through the web site, what is the point of generating it. I'm sure it takes a lot of time.

It is available through the web site. Every library has a top level index.html you can browse to, to read each of them. Some of those will land in the consolidated docs. While others will not. It's the choice of the author which one the prefer to provide.

...

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.

Not checking in the generated docs to git relieves all the other Boost authors from downloading your documentation with every pull.

It also almost guarentees that the local documention will be out of sync with the current library source. Robert Ramey

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

пт, 9 авг. 2024 г. в 03:39, Robert Ramey via Boost :

It also almost guarentees that the local documention will be out of sync with the current library source.

These days this is hardly a problem for anyone but the person currently working on documentation of the library. Internet access is ubiquitous and cheap, very few people (if anyone) actually want local documentation.

On 2024-08-09 22:55, Robert Ramey via Boost wrote: -->%--

But no matter. Here is what I would like to be able to do and I think lots of library users would also.

a) Find a library I want to use, fix, enhance, inspect, try out, or whatever.

b) download the library via github clone.

https://github.com/boostorg/boost/tree/master/libs

c) find one my machine all the source, notes, documentation, examples, tests, etc that I need to use/evaluate the library.

I did that (I forked graph because I want to add), but you can clone as well. All is there, doc, examples, test, ... Here are files I changed or will add to doc, test, later example, ... $ git status . On branch develop Your branch is up to date with 'origin/develop'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) modified: include/boost/graph/detail/adjacency_list.hpp Untracked files: (use "git add <file>..." to include in what will be committed) doc/planar_vertex_coloring.html example/.king_ordering.cpp.swp example/figs/dijkstra-eg.dot example/tst.cpp include/boost/graph/planar_vertex_coloring.hpp test/planar_vertex_coloring.cpp no changes added to commit (use "git add" and/or "git commit -a") $

d) Once I've done the above, I would like to be able to just use the library on my local machine without necessarily being connected to the net. I don't want to have to build anything, install more tools or whatever.

I first installed boost_1_85_0 into my home. Then I made it available: $ ls -l /usr/include | grep boost lrwxrwxrwx 1 root root 10 Aug 1 16:07 boost -> boost_1.85 drwxr-xr-x 129 root root 12288 Mar 9 23:56 boost_1.74 lrwxrwxrwx 1 root root 27 Aug 1 16:06 boost_1.85 -> /home/pi/boost_1_85_0/boost $ Then I cloned my fork of graph into my home. And made it work with 1_85_0: $ ls -l /usr/include/boost/ | grep "graph " lrwxrwxrwx 1 pi pi 35 Aug 7 17:11 graph -> /home/pi/graph/include/boost/graph/ $ I am new to Boost development. So I am not sure whether this is the most elegant way to work with graph. But it works well for me, and my fork allows me to develop as I want: https://github.com/Hermann-SW/graph Regards, Hermann.

On 2024-08-10 08:26, Robert Ramey via Boost wrote:

Note: I was refering to editing and use the documentation for the library.

Yes, but you asked for examples and lib use as well. I did show the location for the graph documentation after cloning: graph/doc/planar_vertex_coloring.html I created that file as a copy of graph/doc/sequential_vertex_coloring.html to start with. And this is how you can use and see progress of your documentation: cd ~/graph/doc wget https://www.boost.org/doc/libs/1_85_0/boost.png python -m http.server Then open "http://127.0.0.1:8000" in your browser. I can see my new page which is not yet linked to directly: http://127.0.0.1:8000/doc/planar_vertex_coloring.html And then edit and refresh browser view. Regards, Hermann Stamm-Wilbrandt.

On 8/9/24 5:35 PM, René Ferdinand Rivera Morell via Boost wrote:

On Fri, Aug 9, 2024 at 3:55 PM Robert Ramey via Boost

...

g) If I make a change in the documentation I would handle it just as I do for code - push the changes.

Does this sound so unreasonable?

Sounds reasonable. I already do that. I also test any examples included in the documentation, automatically. I don't understand your problem.

For the documentation? then why are we doing a special build for it? Robert Ramey

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. E.g. a pull request modifying the doc/html files will get overwritten by the next build, a pull request modifying just the source files won't be reflected in doc/html until the next rebuild, 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).

On 8/10/24 17:07, Robert Ramey via Boost wrote:

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.

Consider a situation when a user notices a typo in your library docs. He is so fond of your library that he is willing to send a PR fixing the typo. He notices that the generated docs committed in git, so he is facing the following alternatives: 1. Fix the typo in the source (QuickBook/BoostBook/whatever), then setup the toolchain to generate the html, run it to regenerate docs on his machine. Put the entire set of changes in his PR. Then maybe notice that his toolchain works slightly differently than yours, which results in massive diffs in the generated html. This is, perhaps, the most positive scenario for you, the maintainer, as it at least preserves the source and the generated html synchronized. It is also the least probable, as in 90% cases the user will abandon the idea on the "setup the toolchain" step. 2. Fix the typo in the source and in the generated html, manually. You will be lucky if the user fixes all instances of the typo in the generated html. Downside: mismatch between source and html is possible. 3. Fix only the source, let the maintainer know that he has to rebuild the html. Or not bother with letting you know. In any case, you merge the PR and then you have to remember to rebuild the html (because, of course, you might be away from your work machine when you merge the PR). Downside: extra burden on you to rebuild the html, mismatch between source and html if you forget. 4. Fix only the html (because "what html generation?" or "why bother with that QuickBook/BoostBook/whatever mumbo-jumbo" or any number of reasons). Downside: extra burden on you to backport that fix to the source or that fix gets overwritten when you generate docs next time. Which may be as soon as the docs are uploaded on the website. 5. Don't fix anything and walk away. Really, don't commit auto-generated docs in git. Just don't.

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.

You do have the documentation with the library - in its source form (i.e. QuickBook/Markdown/AsciiDoc/etc.). Committing the generated html in git is similar to committing compiled binaries of your library in git.

On 8/10/24 2:11 PM, Andrey Semashev via Boost wrote: Good points.

You do have the documentation with the library - in its source form (i.e. QuickBook/Markdown/AsciiDoc/etc.). Committing the generated html in git is similar to committing compiled binaries of your library in git.

BUT how is a potential or current user to access the latest html version of the documentation? Is he expected to generate it himself. Then there's the question of what if the documentation the user is meant to see is located on different branches? In general, who is expected to generate the documentation and when is he expected to do it? And what about the readable documentation out of sync with the code? Robert Ramey

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

On 8/11/24 11:34, Andrey Semashev wrote:

On 8/11/24 03:21, Robert Ramey via Boost wrote:

...

On 8/10/24 2:11 PM, Andrey Semashev via Boost wrote: Good points.

...

You do have the documentation with the library - in its source form (i.e. QuickBook/Markdown/AsciiDoc/etc.). Committing the generated html in git is similar to committing compiled binaries of your library in git.

BUT how is a potential or current user to access the latest html version of the documentation?

He can see it on the website. For example, depending on your definition of "latest":

https://www.boost.org/doc/libs/develop/libs/safe_numerics/doc/html/index.htm... https://www.boost.org/doc/libs/master/libs/safe_numerics/doc/html/index.html https://www.boost.org/doc/libs/release/libs/safe_numerics/doc/html/index.htm...

...

Is he expected to generate it himself.

If visiting the website is not an option for some reason, yes. Although the documentation is fairly readable in its source form already, so generating html is not strictly required.

I should clarify that in the paragraph above I'm assuming the documentation from an arbitrary commit from git (e.g. develop or master snapshot). Generated html documentation for Boost releases is distributed in the release package. Or, based on recent discussions, in the future it may be distributed in a separate package along with the package with the source code. So, for Boost releases, the user already has the built html.

In practice, local documentation is extremely rarely needed these days.

...

Then there's the question of what if the documentation the user is meant to see is located on different branches?

See the links above.

I don't think branches other than master and develop get uploaded to the website, but users aren't (supposed to be) interested in those branches either.

...

In general, who is expected to generate the documentation and when is he expected to do it?  And what about the readable documentation out of sync with the code?

For users' perusal, the documentation is updated on the website automatically per commit to develop and master, or upon Boost releases. So the html documentation is always, though with some small delay, synchronized with git.