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

["Laszlo Ersek" <lersek@redhat.com>]

On 10/19/20 22:33, Kinney, Michael D wrote:
> 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.

No, the current names make sense. Thanks for the explanation.

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

I agree completely. Introducing this small "external dependency" still
leaves us in a lot better situation than what we're in now (which is "no
offline docs").

Thanks for the explanation, and for your work on this!
Laszlo

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