Re: TianoCore-docs GitBook Documentation Process

["Kinney, Michael D" <michael.d.kinney@intel.com>]

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 <lersek@redhat.com>; Kinney, Michael D
> <michael.d.kinney@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:lersek@redhat.com]
> > Sent: Saturday, July 8, 2017 2:36 PM
> > To: Kinney, Michael D <michael.d.kinney@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