Merge pull request 'Add EPUB customizations and improve CI' (#142) from dvzrv/epub_customizations into draft

Reviewed-on: https://codeberg.org/openpgp/notes/pulls/142

.reuse/dep5

@@ -10,3 +10,7 @@ License: CC-BY-SA-4.0
 Files: book/source/mermaid/*.png
 Copyright: 2023  The "Notes on OpenPGP" project
 License: CC-BY-SA-4.0
+
+Files: book/patches/*.patch
+Copyright: 2023  The "Notes on OpenPGP" project
+License: CC0-1.0

.woodpecker/epub.yml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
+# SPDX-License-Identifier: CC0-1.0
+
+clone:
+  git:
+    image: woodpeckerci/plugin-git
+    settings:
+      lfs: false
+
+when:
+  branch: draft
+  event:
+    - push
+    - pull_request
+
+steps:
+  epub-check:
+    image: archlinux:latest
+    commands:
+      - pacman -Sy --needed --noconfirm archlinux-keyring
+      - pacman -Syu --needed --noconfirm epubcheck make patch python-myst-parser python-sphinx
+      # fix sphinx: https://github.com/sphinx-doc/sphinx/issues/11598
+      - patch -Np1 -d /usr/lib/python3.11/site-packages/ -i "$(pwd)/book/patches/sphinx-11766.patch"
+      - make -C book epub-check

Dockerfile

@@ -1,12 +1,15 @@
 # SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
 # SPDX-License-Identifier: CC0-1.0
 
-FROM sphinxdoc/sphinx AS build
-RUN pip install myst-parser
+FROM archlinux:latest AS build
 COPY book/ /book
 WORKDIR /book
-RUN make html
-RUN make epub
+# fix EPUB rendering: https://github.com/sphinx-doc/sphinx/issues/11598
+RUN \
+  pacman -Sy --needed --noconfirm archlinux-keyring \
+  && pacman -Syu --needed --noconfirm epubcheck make patch python-myst-parser python-sphinx \
+  && patch -Np1 -d /usr/lib/python3.11/site-packages/ -i /book/patches/sphinx-11766.patch \
+  && make epub html
 
 FROM scratch
 COPY --from=build /book/build/html /

book/Makefile

@@ -7,6 +7,7 @@
 # You can set these variables from the command line, and also
 # from the environment for the first two.
 CODESPELL ?= codespell
+EPUBCHECK ?= epubcheck
 SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
 LYCHEE ?= lychee
@@ -14,6 +15,9 @@ PRINTF ?= printf
 SOURCEDIR     = source
 BUILDDIR      = build
 
+epub-check: clean epub
+	@$(EPUBCHECK) "$(BUILDDIR)/epub/"*.epub
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

book/patches/sphinx-11766.patch

@@ -0,0 +1,26 @@
+diff --git a/sphinx/builders/html/__init__.py b/sphinx/builders/html/__init__.py
+index 85067be0178..91d3647597c 100644
+--- a/sphinx/builders/html/__init__.py
++++ b/sphinx/builders/html/__init__.py
+@@ -1061,7 +1061,9 @@ def css_tag(css: _CascadingStyleSheet) -> str:
+                     attrs.append(f'{key}="{html.escape(value, quote=True)}"')
+             uri = pathto(os.fspath(css.filename), resource=True)
+             if checksum := _file_checksum(outdir, css.filename):
+-                uri += f'?v={checksum}'
++                # the EPUB format does not allow the use of query components
++                if self.name != 'epub':
++                    uri += f'?v={checksum}'
+             return f'<link {" ".join(sorted(attrs))} href="{uri}" />'
+ 
+         ctx['css_tag'] = css_tag
+@@ -1092,7 +1094,9 @@ def js_tag(js: _JavaScript | str) -> str:
+                 # https://github.com/sphinx-doc/sphinx/issues/11658
+                 pass
+             elif checksum := _file_checksum(outdir, js.filename):
+-                uri += f'?v={checksum}'
++                # the EPUB format does not allow the use of query components
++                if self.name != 'epub':
++                    uri += f'?v={checksum}'
+             if attrs:
+                 return f'<script {" ".join(sorted(attrs))} src="{uri}"></script>'
+             return f'<script src="{uri}"></script>'

book/source/_static/epub/css/custom.css

@@ -0,0 +1,13 @@
+/*
+SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project
+SPDX-License-Identifier: CC0-1.0
+*/
+
+div.admonition {
+  background-color: lightgray;
+}
+
+div.warning,
+div.admonition-warning {
+  background-color: palevioletred;
+}

book/source/conf.py

@@ -24,7 +24,24 @@ source_suffix = ['.md', '.rst']
 templates_path = ['_templates']
 exclude_patterns = []
 
+# number code-blocks, figures and tables, if they have a caption
+numfig = True
+# number figures in flat hierarchy
+numfig_secnum_depth = 0
 
+# -- Options for MyST-parser -------------------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/configuration.html
+
+# we want to circumvent obscure warnings about footnotes following a heading:
+# https://github.com/executablebooks/MyST-Parser/issues/352
+myst_footnote_transition = False
+
+# -- Options for EPUB output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output
+
+epub_css_files = [
+    'epub/css/custom.css'
+]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
@@ -42,12 +59,3 @@ html_theme_options = {
     'show_relbars': 'yes',
     'show_powered_by': False,
 }
-
-# we want to circumvent obscure warnings about footnotes following a heading:
-# https://github.com/executablebooks/MyST-Parser/issues/352
-myst_footnote_transition = False
-
-# number code-blocks, figures and tables, if they have a caption
-numfig = True
-# number figures in flat hierarchy
-numfig_secnum_depth = 0