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 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 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 / 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) 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'' 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..63b6dcd 100644 --- a/book/source/conf.py +++ b/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