From d02239901bcb7f2e7e396ad8e3366509375bdc9a Mon Sep 17 00:00:00 2001 From: David Runge Date: Tue, 12 Dec 2023 14:51:34 +0100 Subject: [PATCH 1/6] Ignore spelling in assets. Signed-off-by: David Runge --- book/.codespellrc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/.codespellrc b/book/.codespellrc index 0ca6c79..280ba35 100644 --- a/book/.codespellrc +++ b/book/.codespellrc @@ -2,4 +2,4 @@ # SPDX-License-Identifier: CC0-1.0 [codespell] -skip = ./build,./input,./source/diag/*.svg,./source/examples/* +skip = ./build,./input,./assets/*/*,./source/examples/* From 650d90d92dcd3eca31c3c427203f2f265b6c9712 Mon Sep 17 00:00:00 2001 From: David Runge Date: Sun, 10 Dec 2023 13:49:39 +0100 Subject: [PATCH 2/6] Trigger a rebuild on watch targets also with html and py files Signed-off-by: David Runge --- book/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/Makefile b/book/Makefile index 2d84c06..865650e 100644 --- a/book/Makefile +++ b/book/Makefile @@ -36,7 +36,7 @@ epub-check: clean epub # use watchexec to rebuild the EPUB whenever a markdown file changes # this target kills *any* open instance of calibre's ebook-viewer, that is currently showing OpenPGPforapplicationdevelopers.epub epub-watch: - @$(WATCHEXEC) --shell bash -e css,md 'make clean epub && ev_pid="$$(pgrep -af "^python3.*ebook-viewer.*OpenPGPforapplicationdevelopers" | cut -f1 -d " ")" && if [[ -n "$$ev_pid" ]]; then kill -9 "$$ev_pid"; fi && $(EBOOK_VIEWER) $(BUILDDIR)/epub/OpenPGPforapplicationdevelopers.epub &' + @$(WATCHEXEC) --shell bash -e css,html,j2,md,py,svg 'make clean epub && ev_pid="$$(pgrep -af "^python3.*ebook-viewer.*OpenPGPforapplicationdevelopers" | cut -f1 -d " ")" && if [[ -n "$$ev_pid" ]]; then kill -9 "$$ev_pid"; fi && $(EBOOK_VIEWER) $(BUILDDIR)/epub/OpenPGPforapplicationdevelopers.epub &' # Put it first so that "make" without argument is like "make help". help: @@ -50,7 +50,7 @@ html-linkcheck: clean html # use watchexec to rebuild the HTML whenever a markdown file changes html-watch: - @$(WATCHEXEC) --shell bash -e css,md 'make clean html' + @$(WATCHEXEC) --shell bash -e css,html,j2,md,py,svg 'make clean html' # spell check all sources # NOTE: diagrams are not yet spell checked, but we emit the required changes From 305949e56e5eee33b2bb7b4b5b1604b93a4d65c5 Mon Sep 17 00:00:00 2001 From: David Runge Date: Sun, 10 Dec 2023 14:07:25 +0100 Subject: [PATCH 3/6] Add jinja template for cover page (used by EPUB renderer) Signed-off-by: David Runge --- book/source/_templates/cover.j2 | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 book/source/_templates/cover.j2 diff --git a/book/source/_templates/cover.j2 b/book/source/_templates/cover.j2 new file mode 100644 index 0000000..0c0e9f7 --- /dev/null +++ b/book/source/_templates/cover.j2 @@ -0,0 +1,20 @@ +{# +SPDX-FileCopyrightText: 2023 The "Notes on OpenPGP" project +SPDX-License-Identifier: CC-BY-SA-4.0 +#} +{%- extends "layout.html" %} +{%- block header %}{% endblock %} +{%- block rootrellink %}{% endblock %} +{%- block relbaritems %}{% endblock %} +{%- block sidebarlogo %}{% endblock %} +{%- block linktags %}{% endblock %} +{%- block relbar1 %}{% endblock %} +{%- block sidebar1 %}{% endblock %} +{%- block sidebar2 %}{% endblock %} +{%- block footer %}{% endblock %} + +{% block content %} +
+ Cover image +
+{% endblock %} From bd59b5bac09fb04fd4446cbc30bb828c2c8b16e2 Mon Sep 17 00:00:00 2001 From: David Runge Date: Sun, 10 Dec 2023 14:10:33 +0100 Subject: [PATCH 4/6] Add custom CSS for cover page (used in EPUB renderer) Signed-off-by: David Runge --- book/source/_static/epub/css/custom.css | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/book/source/_static/epub/css/custom.css b/book/source/_static/epub/css/custom.css index 31ee04f..46b31d2 100644 --- a/book/source/_static/epub/css/custom.css +++ b/book/source/_static/epub/css/custom.css @@ -59,4 +59,13 @@ aside.footnote-list { border-top: 1px solid black; margin-top: 2em; padding-top: 2em; -} \ No newline at end of file +} + +/* +Cover +*/ + +div.cover-img { + margin: auto; + width: 50%; +} From ace6499cbb3d7fe56cb318a81938453c22abe117 Mon Sep 17 00:00:00 2001 From: David Runge Date: Sun, 10 Dec 2023 14:11:11 +0100 Subject: [PATCH 5/6] Update project config to add cover page, log, favicon and improve output Add a logo, favicon and cover image for HTML and EPUB output. Add an author, so that metadata is set properly for EPUB. Extend copyright statement by reusing information and adding links to project and license. Format today as YYYY-MM-DD instead of language specific. Signed-off-by: David Runge --- .reuse/dep5 | 2 +- book/Makefile | 2 +- book/source/_static/epub/img/cover.svg | 263 +++++++++++++++++++++++ book/source/_static/html/img/favicon.ico | Bin 0 -> 4286 bytes book/source/_static/html/img/favicon.svg | 158 ++++++++++++++ book/source/_static/html/img/logo.svg | 137 ++++++++++++ book/source/conf.py | 26 ++- 7 files changed, 583 insertions(+), 5 deletions(-) create mode 100644 book/source/_static/epub/img/cover.svg create mode 100644 book/source/_static/html/img/favicon.ico create mode 100644 book/source/_static/html/img/favicon.svg create mode 100644 book/source/_static/html/img/logo.svg diff --git a/.reuse/dep5 b/.reuse/dep5 index 5c3e72a..3d94d06 100644 --- a/.reuse/dep5 +++ b/.reuse/dep5 @@ -3,7 +3,7 @@ Upstream-Name: notes Upstream-Contact: Heiko Schaefer Source: https://codeberg.org/openpgp/notes -Files: book/assets/* book/source/img/* +Files: book/assets/* book/source/img/* book/source/_static/epub/img/* book/source/_static/html/img/* Copyright: 2023 The "Notes on OpenPGP" project License: CC-BY-SA-4.0 diff --git a/book/Makefile b/book/Makefile index 865650e..d4b9822 100644 --- a/book/Makefile +++ b/book/Makefile @@ -46,7 +46,7 @@ html: convert-svg @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) html-linkcheck: clean html - @$(LYCHEE) "$(BUILDDIR)/html/"*.html + @$(LYCHEE) --exclude "https://openpgp.dev*" --exclude "https://codeberg.org/openpgp/notes" "$(BUILDDIR)/html/"*.html # use watchexec to rebuild the HTML whenever a markdown file changes html-watch: diff --git a/book/source/_static/epub/img/cover.svg b/book/source/_static/epub/img/cover.svg new file mode 100644 index 0000000..5bc03b0 --- /dev/null +++ b/book/source/_static/epub/img/cover.svg @@ -0,0 +1,263 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/book/source/_static/html/img/favicon.ico b/book/source/_static/html/img/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..27ffc73e375ce208621a0706951a24326134d309 GIT binary patch literal 4286 zcmb_gdrXyO82_3pv)pq1(bjFca%q3HxmI(PHZw(6Q!|&{T+Pz9>>nlNVt{x72|>Kz zI)Xw<))X(GI6wvEs-A-g2NjIVffSCQAe{S!U%%&r!wv=~IETmm&ij1t<@r7D^FGh_ zeyAvq@!ymwiu@{nPEwTT6h)a%uuFNLkp4gffI>_pmJoZ065=jl?MEBia^g2)IWdU{ zgi>8AHi*fDaCQHDj%c57UP7f&EVqlGg!?+s)!Ix}mRi;`$9I8k=3P z+j~8B^;9N$`@m<(^Kj3EKw85cH`0z;k#xX@gj6fyG!|^xYeDQj6Ruu&KzySl5Cbky zf02-y2}tS0#)c0v{UhI)e=HFYjj-*Tdo=U1V3LRaNPna+uVQajET*l;S(hRhr* z4xg~%;87d)AL)ztNciJZ%n}26uRKcx^)dJTO1_k8ohU4`A?HE|vh&-Kcgc$UA_sY$ zIGJn3U)fexSJIB;{TW!XY5|sfF$14``4*Ob{Q+VU(vh9l?iYVfp&DSvC6&li z2l!K5uE#g4=OQ{T9hqkg+_QaW+A^&k21!;gecWHaIV;nip{qtd_*R+sP&h)zZGjj^AMe6#OB?dSQVU$4YB_~_=~Sd`KcmFU~FwO zAY$`Uaynr$KSV?0P1tOf{waf-vhsYKFF1+3^T!4d60rblLuPUhzhK^?x3P3ZFy=3w zjpZxDG4sP2cxV1B1bw;^GlPCW`ms(p)uSKauf3`*z=^CB^z?KgBq9h&d)H!X+_!Kz zY=g;%c`}*1d44VGXhYKj#O}U^$Q=f?9%A;kVSP+JB6oIUL*yQ$rpIufeZl7fiGS|J zqHONz1a8(=Kyx69wb_fPt;^8X=HE5wV7k{exKMQ2feWP$=&GH#-|2?KX~)J*i%@ns z-?I}fl~}E=5XVnxU@|?##^}Y^zT@2n?tcKNU^4LkCGEZU` zPQT>*EgWlZxjk&`>l<&N=7x6EC@#%GSk%Yp>gw=tOZz$TB;##N)`a4U_Ja4=kb1Hv z1V4w*#o;6IqsHCVCU2W^->KiJY`5QQzeBroQ1^G0_nbkxk#P!({0O&w%o()6_k+Cq z)H|5%^F+7AU25rMRw~3-yWI-A!-|fMR_5n%tP6b)Rn=v_t&VI|3Txndkht(5# zwIp1dwta>l*G|Qnb<^n6d}N(T!~F+FnKBk4ch11~NB?)gN^N|QA&=;-^2oWu}SSD5sQh5#Bk;Y^`mf{%!Er(X4@2Ha+jh!)1)Zl3l(LY cAd3HeAW%jro^^%&cA98YYzv2Q38!%X3tG)p8vp + diff --git a/book/source/_static/html/img/logo.svg b/book/source/_static/html/img/logo.svg new file mode 100644 index 0000000..b888225 --- /dev/null +++ b/book/source/_static/html/img/logo.svg @@ -0,0 +1,137 @@ + + diff --git a/book/source/conf.py b/book/source/conf.py index 9c10089..48e0bb7 100644 --- a/book/source/conf.py +++ b/book/source/conf.py @@ -6,12 +6,20 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html +from datetime import date + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'OpenPGP for application developers' -copyright = '2023, The "Notes on OpenPGP" project, CC-BY-SA-4.0' -version = "0.01" +author = 'The "Notes on OpenPGP" project' +upstream_url = "https://codeberg.org/openpgp/notes" +license_url = "https://creativecommons.org/licenses/by-sa/4.0/" +copyright = f'{date.today().year}, {author}, CC-BY-SA-4.0' +version = "0.1" +suppress_warnings = [ + 'epub.unknown_project_files', +] # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration @@ -29,6 +37,9 @@ numfig = True # number figures in flat hierarchy numfig_secnum_depth = 0 +# format today as YYYY-MM-DD instead of language specific +today_fmt = "%Y-%m-%d" + # -- Options for MyST-parser ------------------------------------------------- # https://myst-parser.readthedocs.io/en/latest/configuration.html @@ -45,9 +56,12 @@ myst_enable_extensions = [ # -- Options for EPUB output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output +epub_copyright = f'{date.today().year}, {author} ({upstream_url}), CC-BY-SA-4.0' +epub_cover = ('_static/epub/img/cover.svg', 'cover.j2') epub_css_files = [ 'epub/css/custom.css' ] +epub_title = project.replace(" ", "_") # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output @@ -58,13 +72,19 @@ html_css_files = [ ('html/css/custom.css', {'priority': 1000}) ] +html_favicon = '_static/html/img/favicon.ico' +html_logo = '_static/html/img/logo.svg' html_show_sphinx = False -html_show_copyright = False html_show_sourcelink = False +html_title = project # https://github.com/sphinx-doc/alabaster/blob/0.x/alabaster/theme.conf html_theme_options = { 'code_font_size': '9pt', + 'extra_nav_links': { + 'Sources on Codeberg': upstream_url, + 'Download EPUB': f'https://openpgp.dev/epub/{epub_title}.epub', + }, 'show_relbars': 'yes', 'show_powered_by': False, } From e9340c8bda330fec652b3232369962a21817b18c Mon Sep 17 00:00:00 2001 From: David Runge Date: Tue, 12 Dec 2023 14:59:18 +0100 Subject: [PATCH 6/6] Add ASSETSDIR variable to more conveniently address assets dir Signed-off-by: David Runge --- book/Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/Makefile b/book/Makefile index d4b9822..d1e55d2 100644 --- a/book/Makefile +++ b/book/Makefile @@ -16,6 +16,7 @@ LYCHEE ?= lychee PRINTF ?= printf RM ?= rm WATCHEXEC ?= watchexec +ASSETSDIR = assets SOURCEDIR = source BUILDDIR = build @@ -25,7 +26,7 @@ clean-all: clean # convert all SVG to plain SVGs without metadata and paths instead of text convert-svg: - for file in $(SOURCEDIR)/../assets/inkscape/*.svg $(SOURCEDIR)/../assets/drawio/*.svg; do if [[ ! -f $(SOURCEDIR)/plain_svg/$$(basename $$file) ]]; then $(INKSCAPE) --export-text-to-path --export-plain-svg --export-filename=$(SOURCEDIR)/plain_svg/$$(basename $$file) $$file; fi; done + for file in $(ASSETSDIR)/inkscape/*.svg $(ASSETSDIR)/drawio/*.svg; do if [[ ! -f $(SOURCEDIR)/plain_svg/$$(basename $$file) ]]; then $(INKSCAPE) --export-text-to-path --export-plain-svg --export-filename=$(SOURCEDIR)/plain_svg/$$(basename $$file) $$file; fi; done epub: convert-svg @$(SPHINXBUILD) -M epub "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)