Providing a link to GitHub commit from documentation
I've been considering adding commit hash info to some documentation made using the Quickbook/Boostbook/Docbook/b2/bjam toolchain Using git command line git log or ls-remote I can show the necessary hex digit string: commit 5609fa86e37e1b0eae6466065ba6c8eb3ac0ab2f (HEAD -> refactor1) (It would be useful to have the local commit (rather than remote) so that the generated documentation including this has can be pushed up to remote). Paul@hetpD MINGW64 /i/boost/libs/quan/doc (refactor1) $ git log -n1 HEAD > commit.txt That contains commit 5609fa86e37e1b0eae6466065ba6c8eb3ac0ab2f Author: pabristow <pbristow@hetp.u-net.com> Date: Fri Mar 19 15:46:45 2021 +0000 Generated super new version. So this gets this info into a file, but I have yet to see how to get this into the Quickbook or ? during the b2 build. I note that the Boost documentation headers provide this information in the form a link like displayed as d57d645009 with contents https://github.com/boostorg/boost/commit/d57d6450098300343c6fe3a221297915244... but I don't know how this works. Has anyone done anything like this? Suggestions most welcome. Paul
On Fri, Mar 19, 2021 at 10:20 AM Paul A Bristow via Boost <boost@lists.boost.org> wrote:
but I don't know how this works.
I'm not exactly sure what you're asking.. BUT... If you are viewing a source file on GitHub you can press 'y' to be redirected to a link that is tied to the commit ID of the current branch. For example, if you are on this page: <https://github.com/boostorg/json/blob/develop/include/boost/json.hpp> and from there you press 'y' on your keyboard, you will be redirected to the specific commit: <https://github.com/boostorg/json/blob/f55bd4b85edd9b9b9b2d27fb49d66a990aa89001/include/boost/json.hpp> I don't think that the Boost Quickbook process has a way to resolve links to commit IDs which correspond to the branch in which the docs were built (but I could be wrong). Thanks
On 3/19/21 8:19 PM, Paul A Bristow via Boost wrote:
I've been considering adding commit hash info to some documentation made using the Quickbook/Boostbook/Docbook/b2/bjam toolchain
Using git command line git log or ls-remote I can show the necessary hex digit string:
commit 5609fa86e37e1b0eae6466065ba6c8eb3ac0ab2f (HEAD -> refactor1)
(It would be useful to have the local commit (rather than remote) so that the generated documentation including this has can be pushed up to remote).
Paul@hetpD MINGW64 /i/boost/libs/quan/doc (refactor1) $ git log -n1 HEAD > commit.txt
That contains
commit 5609fa86e37e1b0eae6466065ba6c8eb3ac0ab2f Author: pabristow <pbristow@hetp.u-net.com> Date: Fri Mar 19 15:46:45 2021 +0000
Generated super new version.
So this gets this info into a file, but I have yet to see how to get this into the Quickbook or ? during the b2 build.
I note that the Boost documentation headers provide this information in the form a link like displayed as d57d645009 with contents
https://github.com/boostorg/boost/commit/d57d6450098300343c6fe3a221297915244...
but I don't know how this works.
Has anyone done anything like this?
Suggestions most welcome.
If you're trying to put something line "Generated from commit <SHA1>" in the docs, then I don't think you can do this with git, as its commit id depends on the contents. That is, you could do this, but you would have to make a separate commit adding that line, and it would refer to a past commit.
On Fri, Mar 19, 2021 at 1:00 PM Andrey Semashev via Boost < boost@lists.boost.org> wrote:
If you're trying to put something line "Generated from commit <SHA1>" in the docs, then I don't think you can do this with git, as its commit id depends on the contents. That is, you could do this, but you would have to make a separate commit adding that line, and it would refer to a past commit.
To add on to this point, any squash-merges or rebases run the risk of losing the commit in history unless there's a tag or permanent branch to keep the commit from being pruned for being unreachable. -- Keith Bennett
On Fri, Mar 19, 2021 at 12:44 PM Keith Bennett via Boost <boost@lists.boost.org> wrote:
If you're trying to put something line "Generated from commit <SHA1>"
I don't think this is particularly friendly to users, and it is a brittle solution anyway. I know of one library that tries to do this of course, make what you will of the author: <https://github.com/ned14/outcome/blob/b9e664fbf87a4122731f7f19590abad24f1448b8/include/outcome/detail/revision.hpp#L25> Beast simply keeps its own version number which I increment *every* time there are new commits placed on the branch. I do this for Beast because users may need security updates in between Boost releases: <https://github.com/boostorg/beast/commits/master> The tip of the master and develop branches *always* has a version-setting commit. This eliminates any possible confusion about what code someone is using. Thanks
participants (4)
-
Andrey Semashev -
Keith Bennett -
pbristow＠hetp.u-net.com -
Vinnie Falco