From: "Laszlo Ersek" <lersek@redhat.com>
To: devel@edk2.groups.io, michael.d.kinney@intel.com
Subject: Re: [edk2-devel] Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI)
Date: Mon, 19 Oct 2020 20:59:48 +0200 [thread overview]
Message-ID: <499b75ab-a015-9d5d-f383-780c66338d4d@redhat.com> (raw)
In-Reply-To: <MN2PR11MB4461D64C3E698DE7A07093B9D2030@MN2PR11MB4461.namprd11.prod.outlook.com>
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
next prev parent reply other threads:[~2020-10-19 18:59 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-16 3:48 Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI) Michael D Kinney
2020-10-19 18:59 ` Laszlo Ersek [this message]
2020-10-19 20:33 ` [edk2-devel] " Michael D Kinney
2020-10-20 0:26 ` Michael D Kinney
2020-10-20 8:43 ` Laszlo Ersek
2020-10-20 8:42 ` Laszlo Ersek
2020-10-26 18:57 ` Michael D Kinney
2020-10-26 19:19 ` Kirkendall, Garrett
2020-10-26 19:23 ` Michael D Kinney
2020-11-13 22:39 ` Laszlo Ersek
2020-11-30 19:16 ` Shaw, Kevin W
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-list from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=499b75ab-a015-9d5d-f383-780c66338d4d@redhat.com \
--to=devel@edk2.groups.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox