Re: [edk2-devel] Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI)

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

One feature I forgot to mention with this approach is that a developer fork of
a tianocore-docs repo with this Gitbook action enabled provides the developer
the option of enabling the Gitbook action on their fork.  This allows doc edits
to be performed on the developer fork and published versions of the documents
are generated in the gh-pages branch of that fork when a push is made to the
master or release/* branches.  Other branches can be created to work on edits
and on demand GitHub action feature called workflow_dispatch is enabled that
allows the GitHub action to be run on a branch selected from a dropdown.
You can see this drop down called "Run workflow" in the following page:

https://github.com/tianocore-docs/edk2-TemplateSpecification/actions?query=workflow%3A%22Gitbook+Action+Build%22

This removes the need for developers to locally install the Gitbook CLI tools
to verify the published document output.

Best regards,

Mike

> -----Original Message-----
> From: Kinney, Michael D <michael.d.kinney@intel.com>
> Sent: Monday, October 19, 2020 1:34 PM
> To: Laszlo Ersek <lersek@redhat.com>; devel@edk2.groups.io; Kinney, Michael D <michael.d.kinney@intel.com>
> Subject: RE: [edk2-devel] Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI)
> 
> Laszlo,
> 
> Yes.  As a quick implementation, I am converting the source branch name to a directory
> name below gh-pages to store the draft and multiple releases in the single gh-pages
> branch.  I could add more logic to use better path names if you think that is
> required.
> 
> I agree it would be good if we could get the one fix for PUML up streamed to GitbookIO.
> If you look at the following Readme you will see it is no longer maintained.
> 
>     https://github.com/GitbookIO/gitbook
> 
> We are using the majority of the content from the GitbookIO projects,  Only the
> one gitbook plugin for PUML support is being pulled from a fork.
> 
> This does means we need to handle any future issues ourselves, and if that becomes
> too much work, we would have to consider a conversion to a different publishing
> service or a different document source format.
> 
> The current proposal here is a stop gap to make sure the offline documentation
> is made available to the EDK II Community.
> 
> Thanks,
> 
> Mike
> 
> 
> > -----Original Message-----
> > From: Laszlo Ersek <lersek@redhat.com>
> > Sent: Monday, October 19, 2020 12:00 PM
> > To: devel@edk2.groups.io; Kinney, Michael D <michael.d.kinney@intel.com>
> > Subject: Re: [edk2-devel] Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI)
> >
> > On 10/16/20 05:48, Michael D Kinney wrote:
> > > Hello,
> > >
> > > I have been working on addressing the gaps in the transition to
> > > the new GitBook services for the TianoCore documents in the GitBook
> > > markdown format.  The major gap is the loss of the offline PDF,
> > > EPUB, and MOBI formats.
> > >
> > > I have found a GitHub action that performs the equivalent work
> > > of the legacy GitBook server and it supports publishing the HTML,
> > > PDF, EPUB, and MOBI formats in a gh-pages branch of a GitBook
> > > document repository.  The gh-pages branch supports the HTML
> > > web view of the documents and is stored as part of the same
> > > GitHub repository that hosts the document source files.
> > >
> > > I have tried this out on the edk2-TemplateSpecification document
> > > in the Tianocore-Docs GitHub organization.
> > >
> > >     https://github.com/tianocore-docs/edk2-TemplateSpecification
> > >
> > > The following is the link to the GitHub actions YML file that
> > > publishes a draft version of the document from the master branch
> > > and the release versions of the document from and release/* branch.
> > >
> > >     https://github.com/tianocore-docs/edk2-TemplateSpecification/blob/master/.github/workflows/gitbook-action.yml
> > >
> > > GitBook Action:
> > > * Source: https://github.com/ZanderZhao/gitbook-action
> > > * Docs: https://zlogs.net/gitbook-action/
> >
> > Does the above mean that the "GitHub actions YML" file produces a new
> > commit on the gh-pages branch, generated at a particular state
> > (checkout) of the master branch?
> >
> > Also, where is the PDF format stored?
> >
> > >
> > > I found a few issues with the support of embedded PlantUml
> > > diagrams.  A fork of the GitBook puml plugin is available
> > > that addresses these issues.  The book.json file is updated
> > > to use this newer plugin.
> > >
> > >   "plugins": ["puml-aleung"],
> > >
> > > Links to the GitBook puml pluigis:
> > >
> > > Original: https://github.com/GitbookIO/plugin-puml
> > > Updated:  https://github.com/aleung/gitbook-plugin-puml
> >
> > It would be nice if the updates could be upstreamed from aleung's space
> > to GitbookIO.
> >
> > >
> > > The following are the links to the EDK II Template Specification
> > > documents published by this Gitbook Action.  Notice that all the
> > > links are to files in either GitHub repos or the web pages published
> > > by GitHub when a gh-pages branch is present and updated.
> > >
> > > Draft versions from master branch:
> > >
> > > HTML: https://tianocore-docs.github.io/edk2-TemplateSpecification/master
> >
> > Ugh, confusing. It says "master". I guess it still consumes the
> > "gh-pages" branch.
> >
> > > PDF:  https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/master/mybook/ebook.pdf
> >
> > Hmmm. This seems to answer multiple of my questions above. Indeed this
> > binary PDF file exists in the original repo, it is on the gh-pages
> > branch, and "master" is a pathname component (likely showing the branch
> > name that provided the markdown source code for the rendering).
> >
> > > EPUB: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/master/mybook/ebook.epub
> > > MOBI: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/master/mybook/ebook.mobi
> > >
> > > Release versions from release/0.2 branch:
> > >
> > > HTML: https://tianocore-docs.github.io/edk2-TemplateSpecification/release-0.2
> > > PDF:  https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/release-0.2/mybook/ebook.pdf
> > > EPUB: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/release-0.2/mybook/ebook.epub
> > > MOBI: https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/release-0.2/mybook/ebook.mobi
> > >
> > > In order to enable this on all the documents in Tianocore-docs, the
> > > following tasks need to be performed on each document repo:
> > > * Update book.json in master and release/* branches to use the
> > >   newer PlantUML plugin.
> >
> > Again, upstreaming to GitbookIO would be nice. At this time,
> >
> >   https://github.com/aleung/gitbook-plugin-puml
> >
> > reports
> >
> >   "This branch is 2 commits ahead of GitbookIO:master"
> >
> > hmmm... oh wait, the relevant commit is also the subject of PR#8 for
> > GitbookIO/plugin-puml:
> >
> >   https://github.com/GitbookIO/plugin-puml/issues/8
> >
> > So why was that PR abandoned?...
> >
> > > * Add the file .github/workflows/gitbook-action.yml to the
> > >   master and release/* branches.
> > > * Force a document build on the master and release/* branches to
> > >   publish all draft and release versions of the documents.
> > >
> > > Please review the content here and the published documents and let
> > > me know if there are any concerns with switching to a GitHub
> > > Action to publish all Tianocore Gitbook markdown based documents.
> >
> > Thank you for researching this!
> >
> > My only concern is that I'd prefer our action scripts to consume
> > https://github.com/GitbookIO rather than https://github.com/aleung/ , in
> > the long term. I'd think the former should give us better support in the
> > long term -- although, that may be a foolish hope, given that the
> > PlantUml diagrams issue is only fixed in the latter, at the moment :/
> >
> > Can we somehow talk to Leo Liang? I think we should understand why the
> > PlantUML fix is not part of the offical GitbookIO repo.
> >
> > Thanks!
> > Laszlo