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

[Michael D Kinney]

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/

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

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
PDF:  https://github.com/tianocore-docs/edk2-TemplateSpecification/raw/gh-pages/master/mybook/ebook.pdf
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.
* 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.

Thanks,

Mike


-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#66308): https://edk2.groups.io/g/devel/message/66308
Mute This Topic: https://groups.io/mt/77544104/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-