TianoCore-docs GitBook Documentation Process

TianoCore-docs GitBook Documentation Process

[Kinney, Michael D]

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.

Thanks,

Mike

Re: TianoCore-docs GitBook Documentation Process

[Laszlo Ersek]

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?)


(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?

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


(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'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.)

... 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.


(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.)


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

Re: TianoCore-docs GitBook Documentation Process

[Kinney, Michael D]

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

Re: TianoCore-docs GitBook Documentation Process

[Laszlo Ersek]

Hello Mike,

On 07/10/17 18:43, Kinney, Michael D wrote:
> 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.

thank you for the answers, they are very helpful. I'll highlight one thing:

> 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.

I did not miss the bidirectional arrow :) in the top diagram of
<https://github.com/tianocore-docs/edk2-TemplateSpecification/wiki/TianoCore-Documents-GitBook-Overview>,
between "GitHub tianocore-docs" and "GitBook tianocore-docs". I was
wondering if the left-pointing arrow was an oversight :)

So apparently it's not. We'll have to be careful to avoid WYSIWYG
editing on GitBook.com (personally I'd like to avoid that even for my
forks too). I guess one way to stay safe is to remain logged out of the
GitHub & GitBook websites most of the time (which is how I've been
operating anyway).

Thanks!
Laszlo

Re: TianoCore-docs GitBook Documentation Process

[Kinney, Michael D]

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

Re: TianoCore-docs GitBook Documentation Process

[Laszlo Ersek]

On 07/11/17 17:21, Kinney, Michael D wrote:
> 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": {}
>  }

Ah, great!

Does the fact that the plugin list is provided in the book itself (in
"book.json") imply that gitbook.com too will load the plugin, and
generate the right output, in these "remote" renderings?

Thank you,
Laszlo

Re: TianoCore-docs GitBook Documentation Process

[Kinney, Michael D]

> -----Original Message-----
> From: Laszlo Ersek [mailto:lersek@redhat.com]
> Sent: Tuesday, July 11, 2017 10:05 AM
> To: Kinney, Michael D <michael.d.kinney@intel.com>
> Cc: edk2-devel@lists.01.org
> Subject: Re: [edk2] TianoCore-docs GitBook Documentation Process
> 
> On 07/11/17 17:21, Kinney, Michael D wrote:
> > 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": {}
> >  }
> 
> Ah, great!
> 
> Does the fact that the plugin list is provided in the book
> itself (in
> "book.json") imply that gitbook.com too will load the plugin,
> and
> generate the right output, in these "remote" renderings?

Yes.  When building locally, you need to run "gitbook install"
to install all plugins locally.  The GitBook server automatically
does this step as part of the publication action.

> 
> Thank you,
> Laszlo

Re: TianoCore-docs GitBook Documentation Process

[Kinney, Michael D]

Hello,

I have invited package maintainers listed in the edk2/master
MAINTAINERS.txt file to the new EDK II Maintainers Team in
the Tianocore-Docs organization.  This new team has write
access to the document repositories in Tianocore-Docs
organization.

Please let me know if you did not receive an invite and
you require write access to the document repositories.

Thanks,

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

Re: TianoCore-docs GitBook Documentation Process

[Laszlo Ersek]

On 07/10/17 18:43, Kinney, Michael D wrote:

>> -----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

>> [...] 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.

I learned about two features related to branches:

- The set of branches to build can be configured on the book's settings
page (after setting up integration with github). This page also lets the
user select the branch for the default rendering.

- In order to view the rendering of a non-default branch (from the set
of branched configured above), simply append "/v/BRANCH_NAME" to the
default rendering URL (which is
"https://<username>.gitbooks.io/<book-name>/content"). This is explained
here:

https://help.gitbook.com/content/how-can-i-access-a-specific-version.html

It seems to work for me.

Thanks!
Laszlo