Laszlo, I found a GitBook plugin that can provide the branch name and the SHA hash in either short or long form.
https://plugins.gitbook.com/plugin/gitversion Here is an example patch to the EDK II Template Specification That add this plugin to book.json and add the branch name and SHA hash below the build time/date stamp of the document. diff --git a/README.md b/README.md index 30edb2a..4ad8a96 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,10 @@ ** {{ gitbook.time|date('MM/DD/YYYY hh:mm:ss') }} ** +** {{ "GIT branch: " | gitBranch }} ** + +** {{ "GIT hash: " | gitLong }} ** + {% if book.udkrelease %} ** {{ book.udkrelease }} ** {% endif %} diff --git a/book.json b/book.json index 8c58ffe..d94cbcc 100644 --- a/book.json +++ b/book.json @@ -5,6 +5,6 @@ "version" : "Revision 0.20" }, - "plugins": ["puml"], + "plugins": ["puml", "gitversion"], "pluginsConfig": {} } Best regards, Mike > -----Original Message----- > From: Kinney, Michael D > Sent: Monday, July 10, 2017 9:44 AM > To: Laszlo Ersek <ler...@redhat.com>; Kinney, Michael D > <michael.d.kin...@intel.com> > Cc: edk2-devel@lists.01.org > Subject: RE: [edk2] TianoCore-docs GitBook Documentation Process > > Hi Laszlo, > > Thanks for the quick feedback on this content. > > Reponses included below, and I have already made some > updates to the wiki based on your feedback. > > Mike > > > -----Original Message----- > > From: Laszlo Ersek [mailto:ler...@redhat.com] > > Sent: Saturday, July 8, 2017 2:36 PM > > To: Kinney, Michael D <michael.d.kin...@intel.com> > > Cc: edk2-devel@lists.01.org > > Subject: Re: [edk2] TianoCore-docs GitBook Documentation > Process > > > > Hi Mike, > > > > On 07/08/17 02:37, Kinney, Michael D wrote: > > > Hello, > > > > > > I have added wiki pages that provide an overview of the > > GitBook documentation > > > process for TianoCore related documents. These wiki pages > are > > attached to the > > > EDK II Template Specification repository. The link to the > > approved RFC on this > > > topic is also provided. > > > > > > https://github.com/tianocore-docs/edk2- > > TemplateSpecification/wiki > > > > > > https://github.com/tianocore-docs/edk2- > > TemplateSpecification/wiki/TianoCore-Documents-GitBook- > > Overview#introduction > > > > > > I have also added a link to this content from the EDK II > > Specification wiki page: > > > > > > https://github.com/tianocore/tianocore.github.io/wiki/EDK- > II- > > Specifications > > > > > > Please review and provide feedback if there are steps that > are > > missing or need clarification. > > > > This is a large set of articles, it must have been a lot of > > work! > > > > I have four questions/ideas: > > > > > > (1) The article at > > <https://github.com/tianocore-docs/edk2- > > TemplateSpecification/wiki/TianoCore-Documents-Services> > > says, > > > > 3. Join the TianoCore-Docs organization on GitHub > > > > Can you send an invite? :) On the org page > > <https://github.com/tianocore-docs/>, I looked for a button > > saying > > "request an invite" or some such, but came up empty. > > > > So what is the github way for joining an organization? I guess > > the org > > can send out invites at will, but "solicitation" in the other > > direction > > has to occur off-site? (Such as on this mailing list?) > > I do not see a way for a developer to do the request either, so > sending > an invite looks to be the way to go here. I would like the EDK > II > Maintainers that have write access to code to have same write > access to > Docs. I will send those invites. > > If anyone else wants write access that is not an EDK II > Maintainer, > then they would have to send an email request to edk2-devel. > > I have updated the following page with the email request > instructions > > https://github.com/tianocore-docs/edk2- > TemplateSpecification/wiki/TianoCore-Documents-Services > > > > > > > (2) The article at > > <https://github.com/tianocore-docs/edk2- > > TemplateSpecification/wiki/TianoCore-Documents-GitBook- > Overview> > > explains that there is some kind of (automated) syncing from > the > > tianocore-docs repos to GitBook.com. > > > > In case I'm looking at one of the official document git repos > on > > GitHub, > > such as <https://github.com/tianocore-docs/SecurityAdvisory>, > > what is > > the fastest way to see an HTML rendered "DRAFT" (matching the > > master > > branch) on GitBook.com? Is there some URL pattern that one can > > compose > > manually, or is there a way to search for the book quickly on > > GitBook.com? > > A couple ways: > > 1) Goto the GitBook homepage for tianocore-docs > > https://www.gitbook.com/@edk2-docs > > All the books are listed and you can select any one > of them. The main page for a book has a "Read" button > for the HTML version and a drop down box for PDF, MOBI, > EPUB. > > I have added this link to the intro paragraph and the > "Resources" > section on the TianoCore Documents GitBook Overview wiki > page: > > https://github.com/tianocore-docs/edk2- > TemplateSpecification/wiki/TianoCore-Documents-GitBook-Overview > > > 2) Goto GitBook.com, select "Explore" tab at the top, and enter > keywords into searchbox in upper right. > > If you type in a keyword such as "edk2" or "tiano" or > something > more specific like "fdf" you will see the search results > for the books. If you select one of the books, it will take > you to > the main page for that book where you can select the "Read" > button > to read the HTML version, and there is a drop down for the > PDF, MOBI, > and EPUB versions. > > > > > In > > <https://github.com/tianocore-docs/edk2- > > TemplateSpecification/wiki/TianoCore-Documents-Releasing>, > > I see > > > > 7. Wait a few minutes and verify that the released version > of > > the > > document has been published by the GitBook server > > > > Verify how? > > > > Hmmm... OK, so I think I found the links. They are on this > page: > > > > https://github.com/tianocore/tianocore.github.io/wiki/EDK-II- > > Draft-Specification > > > > The HTML link patterns are like: > > > > https://edk2-docs.gitbooks.io/edk-ii-build-specification/ > > https://edk2-docs.gitbooks.io/edk-ii-dec-specification/ > > https://edk2-docs.gitbooks.io/edk-ii-inf-specification/ > > > > I think this is a bit cumbersome. What do you think of the > > following > > suggestion: in each document source code repository, modify > the > > README.md file so that at the top, it offer a set of links, > > saying: > > > > View this DRAFT specification rendered as: > > [HTML] -> link points to gitbook.com > > [PDF] -> link points directly to PDF download from > > gitbook.com > > > > Finding the links to the latest draft of a document can be found > by looking for the document on https://www.gitbook.com/@edk2- > docs. > > However, finding release branch versions is more challenging. > > I like the idea of the links being in the README.md. Maybe as > hyperlinks in the Revision History section or the in the file > header comment block at the top of the file. I will experiment > with a few styles and will propose some formats. > > > > > (3) (This is somewhat similar to (2).) > > > > Assuming I make a local docs change, and push it to my > personal > > fork on > > GitHub, how can I review that change on GitBook.com, rendered > as > > HTML > > (or, say, PDF)? > > > > The article at > > <https://github.com/tianocore-docs/edk2- > > TemplateSpecification/wiki/TianoCore-Documents-Editing> > > says, > > > > 14. Push branch to developer's fork of the documents > > repository > > * GitBook project linked to developer's fork of the > > document can > > also be setup and used to review the changes and > > formatting > > before sending patch review email to the community. > > > > How can I do this linking? > > I did not write up the details on this yet. Basic concept is > that > you create a personal GitBook account and you enable the GitHub > integration feature. Then you create a new document in your > personal > GitBook area, and you have the option to link to a GitHub repo. > Select > your personal GitHub repo(that is a fork of tianocore-docs repo) > for > the document and GitBook publishes the docs in your personal > GitBook > account. > > I did not end up using this method, because the builds I could > do on > my local system were good enough for me to do edits and review > the > locally published docs. I have noted some minor differences > between > the local builds and the official GitBook builds, but those are > mainly > in the header/footer content on PDF formats. > > > > > (I'm aware that a local npm / gitbook toolchain can be used > for > > reviewing the rendered output locally, but I'm curious about > > this > > "remote rendering" service too.) > > > > In particular, the article at > > <https://github.com/tianocore-docs/edk2- > > TemplateSpecification/wiki/TianoCore-Documents-Services> > > does not say that a developer can, or should, register an > > account > > separately on GitBook.com, and set up periodic pulls for > his/her > > personal GitHub repos. Is that how it's supposed to work? (I'm > > just > > guessing.) > > A GitBook account is not required. With the GitHub integration > that > GitBook provides, we can focus the account management in the > GitHub > side and do all content changes in GitHub repos. The GitBook > integration with GitHub is actually a bidirectional sync, so I > found > it confusing to do edits from both sides. Also, an edit from > the > GitBook side does not follow the TianoCore patch/review process. > > There are no issues with using a personal GitBook account on a > personal fork of a document and using GitBook side to do edits > and view the published documents. But the commits will have to > be cleaned up before sending to edk2-devel for review. > > > > > ... Hmmm okay, according to <https://www.gitbook.com/>, at > least > > a > > separate account doesn't appear necessary. > > > > Reiterating the above README.md idea, the DeLuxe solution > would > > be if we > > could place some kind of macro near the top of the README.md > > file that > > would automatically point to the GitBook.com rendering of the > > *referring* repository. So if you clicked the link while > viewing > > an > > official source repo of the tianocore-docs org, GitBook.com > > would give > > you a rendering of that, but if you clicked the same link in a > > personal > > src repo, GitBook.com would provide a rendering of *that*. > > > > Anyway, this level of automation is not necessary, I'd just > like > > to > > understand what the most direct way is to get GitBook.com > render > > any > > branch from either an official docs repo, or a personal docs > > repo. > > I will do some experiments with these ideas. > > > > > > > (4) It would be nice if the (semi-)live renderings on > > GitBook.com > > automatically displayed the git commit hash of the source > that's > > been > > rendered. > > > > I see there's a timestamp, for example at > > <https://edk2-docs.gitbooks.io/edk-ii-dec- > > specification/content/>: > > > > DRAFT FOR REVIEW > > 04/27/2017 01:14:37 > > > > But: there is no time zone, plus I don't know what event that > > timestamp > > identifies. Patch authorship date? Patch commit date? Pull > date? > > Rendering date? A commit hash would be better. (Not sure if we > > can do > > anything about this; perhaps this would be a new GitBook.com > > feature.) > > I believe the timestamp represent the time that the GitBook > server > performed the publication action. Which is a few seconds to a > few > minutes after the last commit(depending on the size of the doc). > > Adding the SHA hash is a good idea. I will see if there is a > way > to do that. > > > > > > > Sorry if (some of) these questions are already explained in > the > > Wiki, > > it's quite a bit of info to absorb at once :) > > > > Thanks! > > Laszlo _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel