From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by mx.groups.io with SMTP id smtpd.web10.3499.1603133996888924804 for ; Mon, 19 Oct 2020 11:59:57 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@redhat.com header.s=mimecast20190719 header.b=go+0QAfu; spf=pass (domain: redhat.com, ip: 63.128.21.124, mailfrom: lersek@redhat.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1603133996; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=yBngHwG9GptMq0IJDo3JrZUyojRjp7Ong7oEQZIav0E=; b=go+0QAfuA4q0Bqz2CPf92ZqpJ94uM2wisDw6S69nxAFDb8K6P+VvKU5FOY/R4vv3iH8rsV B1FFOmq+qxtHNfLhnogut6zvzJmbD1JXFX+Ht8jrJJ7Z99VaK4W2fpoZo0ovuC4HO1TgVt PfHI+tE4kreiWcXcuHtheESkWPihg8s= Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-358-e8KSnjeHMeWKTEYpBWj5yA-1; Mon, 19 Oct 2020 14:59:51 -0400 X-MC-Unique: e8KSnjeHMeWKTEYpBWj5yA-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 8C661800597; Mon, 19 Oct 2020 18:59:50 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-113-137.ams2.redhat.com [10.36.113.137]) by smtp.corp.redhat.com (Postfix) with ESMTP id A1D955D9EF; Mon, 19 Oct 2020 18:59:49 +0000 (UTC) Subject: Re: [edk2-devel] Tianocore-docs Gitbook offline document status (PDF, EPUB, MOBI) To: devel@edk2.groups.io, michael.d.kinney@intel.com References: From: "Laszlo Ersek" Message-ID: <499b75ab-a015-9d5d-f383-780c66338d4d@redhat.com> Date: Mon, 19 Oct 2020 20:59:48 +0200 MIME-Version: 1.0 In-Reply-To: X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=lersek@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit 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