From ec761273df6d6288458ab19320c1a2d645a12cbe Mon Sep 17 00:00:00 2001 From: David Runge Date: Wed, 22 Nov 2023 22:32:53 +0100 Subject: [PATCH 1/8] Modify CSS for admonition environments when building EPUB Add a lightgray `background-color` for all admonition environments. Add a palevioletred `background-color` for all admonition-warning and warning environments. Signed-off-by: David Runge --- book/source/_static/epub/css/custom.css | 13 +++++++++++++ book/source/conf.py | 5 +++++ 2 files changed, 18 insertions(+) create mode 100644 book/source/_static/epub/css/custom.css diff --git a/book/source/_static/epub/css/custom.css b/book/source/_static/epub/css/custom.css new file mode 100644 index 0000000..40ca147 --- /dev/null +++ b/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; +} \ No newline at end of file diff --git a/book/source/conf.py b/book/source/conf.py index 96f5eb4..abacb6f 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -24,7 +24,12 @@ source_suffix = ['.md', '.rst'] templates_path = ['_templates'] exclude_patterns = [] +# -- 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 From 34f94f780291a90490440f458922b3b2d2a317d9 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 10:50:44 +0100 Subject: [PATCH 2/8] Move numfig configuration to general configuration Signed-off-by: David Runge --- book/source/conf.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/book/source/conf.py b/book/source/conf.py index abacb6f..26f49db 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -24,6 +24,11 @@ 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 EPUB output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output @@ -51,8 +56,3 @@ html_theme_options = { # 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 From d7d34d49406b31246617a24c0a71cb1202b0028c Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 10:52:18 +0100 Subject: [PATCH 3/8] Move MyST-parser configuration to its own section Signed-off-by: David Runge --- book/source/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/book/source/conf.py b/book/source/conf.py index 26f49db..63b6dcd 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -29,6 +29,13 @@ 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 @@ -52,7 +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 From 8f1d939ddbccae92fec333a1efcd5564ad7003ec Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:00:05 +0100 Subject: [PATCH 4/8] Add make target to check a cleanly built EPUB using epubcheck Signed-off-by: David Runge --- book/Makefile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/book/Makefile b/book/Makefile index a4c41c9..8e84021 100644 --- a/book/Makefile +++ b/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) From 57f62222d20bfabfab9f987de03df17379400983 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 13:16:46 +0100 Subject: [PATCH 5/8] Add reuse config for patches Signed-off-by: David Runge --- .reuse/dep5 | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.reuse/dep5 b/.reuse/dep5 index bee0e46..6ff7050 100644 --- a/.reuse/dep5 +++ b/.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 From ccddbe42041f123707a58b719a0fc45abd341576 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:01:01 +0100 Subject: [PATCH 6/8] Add local copy of upstreamed sphinx patch for CSS issues with EPUBs The patch fixes https://github.com/sphinx-doc/sphinx/issues/11598 for sphinx >= 7.2.0 Signed-off-by: David Runge --- book/patches/sphinx-11766.patch | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 book/patches/sphinx-11766.patch diff --git a/book/patches/sphinx-11766.patch b/book/patches/sphinx-11766.patch new file mode 100644 index 0000000..c507523 --- /dev/null +++ b/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'' + + 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'' + return f'' From eeb1de8ab706af426aeda4ce464f87e5a107aeb1 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:02:34 +0100 Subject: [PATCH 7/8] Add woodpecker integration for building and testing the EPUB Signed-off-by: David Runge --- .woodpecker/epub.yml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .woodpecker/epub.yml diff --git a/.woodpecker/epub.yml b/.woodpecker/epub.yml new file mode 100644 index 0000000..798fbea --- /dev/null +++ b/.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 From 02c7b04cfd2fb58a96777a521f039f42c4ba3ef9 Mon Sep 17 00:00:00 2001 From: David Runge Date: Fri, 24 Nov 2023 12:49:20 +0100 Subject: [PATCH 8/8] Adapt Containerfile to build with a patched version of sphinx Sphinx >= 7.1.0 has issues rendering EPUBs correctly. Install latest sphinx and apply a patch to fix EPUB rendering. Signed-off-by: David Runge --- Dockerfile | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Dockerfile b/Dockerfile index 3941373..24aadea 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,13 +1,16 @@ # 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 / -COPY --from=build /book/build/epub/OpenPGPforapplicationdevelopers.epub / \ No newline at end of file +COPY --from=build /book/build/epub/OpenPGPforapplicationdevelopers.epub /