From 7743f2d88f67999a6b074c06a8462fec862dc71c Mon Sep 17 00:00:00 2001 From: Mladen Milankovic Date: Mon, 14 Sep 2026 18:02:26 +0200 Subject: [PATCH] Give the PDF the same cover and layout as the other manuals Take the LaTeX setup from the cryptnox-cli manual: cover page with the logo, title, release and date, no filler pages, sans-serif body, left-aligned chapter headings, running header and copyright footer. The dark cover logo is generated from the site SVG at build time, so cairosvg and Pillow join the build requirements. Keep the site-only parts of the index page out of the PDF: the download link, the landing card and the Other resources list. The three articles are now the PDF's chapters instead of sitting under a chapter made of the index page. Co-Authored-By: Claude Fable 5.1 --- .gitignore | 2 + docs/source/conf.py | 112 ++++++++++++++++++++++++++++++++++++++++-- docs/source/index.rst | 54 ++++++++++---------- requirements.txt | 2 + 4 files changed, 138 insertions(+), 32 deletions(-) diff --git a/.gitignore b/.gitignore index 4cc05d4..531b198 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ docs/_build/ _site/ __pycache__/ +# generated from cryptnox-logo.svg by conf.py for the PDF cover +docs/source/_static/cryptnox-logo-dark.png diff --git a/docs/source/conf.py b/docs/source/conf.py index 7e617d6..a4335c0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,5 +1,31 @@ # Configuration file for the Sphinx documentation builder. +import io +import os + +# Derive the navy PDF cover logo from the white HTML SVG at build time, so only +# the SVG is a committed source asset (needs cairosvg + Pillow, both in +# requirements.txt). +try: + import cairosvg + from PIL import Image +except ImportError as e: + raise RuntimeError( + "The docs build needs cairosvg and Pillow to generate the PDF cover logo; " + "install them with: pip install -r requirements.txt" + ) from e + +_static = os.path.join(os.path.dirname(__file__), '_static') +with open(os.path.join(_static, 'cryptnox-logo.svg'), encoding='utf-8') as f: + _svg = f.read() +_png = cairosvg.svg2png( + bytestring=_svg.replace('fill="white"', 'fill="#101f2e"').encode(), + output_width=1200, output_height=226, +) +Image.open(io.BytesIO(_png)).save( + os.path.join(_static, 'cryptnox-logo-dark.png'), dpi=(400, 400) +) + # -- Project information ----------------------------------------------------- project = 'Cryptnox Smart Card Readers' @@ -62,20 +88,96 @@ html_show_sphinx = False # -- Options for PDF (LaTeX) output ------------------------------------------ +# Built by CI with pdflatex; same cover and page layout as the cryptnox-cli +# manual. Output: cryptnox-readers.pdf latex_engine = 'pdflatex' +latex_logo = '_static/cryptnox-logo-dark.png' # generated above; the white logo is invisible on the white cover latex_documents = [ - ('index', 'cryptnox-readers.tex', 'Cryptnox Smart Card Readers', - 'Cryptnox SA', 'manual'), + ('index', 'cryptnox-readers.tex', 'Cryptnox Smart Card Readers Manual', author, 'manual'), ] latex_elements = { 'papersize': 'a4paper', - 'pointsize': '10pt', - # pdflatex has no glyphs for the ✅/❌ marks used in the compatibility - # tables; map them to pifont's check and cross so the PDF builds. + 'pointsize': '11pt', + 'figure_align': 'H', + 'sphinxsetup': 'pre_border-radius=0pt', # sharp rectangle corners on code-block frames + 'extraclassoptions': 'oneside,openany', # no blank filler pages (web PDF) + 'printindex': '', # no general Index in the PDF + 'fncychap': '', # no fancy chapter rules; titlesec styles chapters instead 'preamble': r''' +% pdflatex has no glyphs for the ✅/❌ marks used in the compatibility tables; +% map them to pifont's check and cross \usepackage{pifont} \DeclareUnicodeCharacter{2705}{\ding{51}} \DeclareUnicodeCharacter{274C}{\ding{55}} +% Literals (\ttfamily) in Inconsolata +\usepackage{inconsolata} +% Left-align body text (ragged right instead of justified) +\usepackage[document]{ragged2e} +% Drop the "(continues on next page)" / "(continued from previous page)" labels on code blocks +\AtBeginDocument{\renewcommand*\sphinxstylecodecontinued[1]{}\renewcommand*\sphinxstylecodecontinues[1]{}} +% Whole document in the sans font (TeX Gyre Heros) +\renewcommand{\familydefault}{\sfdefault} +% Sans-serif TOC entries +\AtBeginDocument{\addtocontents{toc}{\protect\sffamily}} +% Left-aligned chapter headings +\usepackage{titlesec} +\titleformat{\chapter}[hang]{\sffamily\bfseries\huge}{\thechapter}{1em}{} +\titlespacing*{\chapter}{0pt}{0pt}{20pt} +% Centered page header (manual title) + copyright footer +\usepackage{fancyhdr} +\def\headruleskip{4pt}\def\footruleskip{4pt}% gap between header/footer text and rule +\AtBeginDocument{% + \fancypagestyle{normal}{% + \fancyhf{}% + \fancyhead[C]{\sffamily\nouppercase{Cryptnox Smart Card Readers Manual}}% + \fancyfoot[L]{\sffamily\copyright{} 2026 Cryptnox SA}% + \fancyfoot[R]{\sffamily\thepage}% + \renewcommand{\headrulewidth}{0.4pt}% + \renewcommand{\footrulewidth}{0.4pt}% + }% + \fancypagestyle{plain}{% + \fancyhf{}% + \fancyfoot[L]{\sffamily\copyright{} 2026 Cryptnox SA}% + \fancyfoot[R]{\sffamily\thepage}% + \renewcommand{\headrulewidth}{0pt}% + \renewcommand{\footrulewidth}{0.4pt}% + }% + \pagestyle{normal}% +} +% Cover page: logo, title, release and date; no author line (the logo brands it) +\makeatletter +\renewcommand{\sphinxmaketitle}{% + \let\sphinxrestorepageanchorsetting\relax + \ifHy@pageanchor\def\sphinxrestorepageanchorsetting{\Hy@pageanchortrue}\fi + \hypersetup{pageanchor=false}% + \begin{titlepage}% + \let\footnotesize\small \let\footnoterule\relax + \begingroup + \def\endgraf{ }\def\and{\& }% + \pdfstringdefDisableCommands{\def\\{, }}% + \hypersetup{pdfauthor={\@author}, pdftitle={\@title}}% + \endgroup + \noindent\rule{\textwidth}{1pt}\par + \begin{flushright}% + \vskip 1em% + \includegraphics[width=7cm]{cryptnox-logo-dark}\par + \vskip 2em% + {\LARGE\py@HeaderFamily \@title \par}% + \vskip 0.5em% + {\large\itshape \py@release\releaseinfo \par}% + \vfill + {\large \@date \par}% + \end{flushright}% + \@thanks + \end{titlepage}% + \setcounter{footnote}{0}% + \let\thanks\relax\let\maketitle\relax + \clearpage + \ifdefined\sphinxbackoftitlepage\sphinxbackoftitlepage\fi + \if@openright\cleardoublepage\else\clearpage\fi + \sphinxrestorepageanchorsetting +} +\makeatother ''', } diff --git a/docs/source/index.rst b/docs/source/index.rst index b3ded4e..b07caf3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -7,30 +7,32 @@ Cryptnox Smart Card Readers ============================ -`Download this documentation as a PDF `__ +.. only:: html + `Download this documentation as a PDF `__ -Compatibility guides -==================== -.. raw:: html + Compatibility guides + ==================== -
- - - - - -
+ .. raw:: html -*Cryptnox USB smart card readers* connect contact (ISO 7816) and contactless (ISO 14443) -smart cards to Windows, macOS and Linux over USB-C. Both readers support extended APDU, -which is what national eID schemes and ICAO 9303 travel documents require for certificates -and signatures larger than the 255/256-byte short-APDU limit. +
+ + + + + +
-* **Smart Card Reader Compatibility by Country** [`HTML `__] — national eID and professional card compatibility per country, with the official government middleware required for each -* **FIDO2 Card Compatibility — Services and Platforms** [`HTML `__] — which services and operating systems work with a Cryptnox FIDO2 NFC card, second-factor or passwordless, and where extra software is needed -* **Click-to-Tap — FIDO2 User Presence on a Desktop Reader** [`HTML `__] — what the Click-to-Tap button does, why FIDO2 sign-in on a contact reader needs it, its requirements, and troubleshooting + *Cryptnox USB smart card readers* connect contact (ISO 7816) and contactless (ISO 14443) + smart cards to Windows, macOS and Linux over USB-C. Both readers support extended APDU, + which is what national eID schemes and ICAO 9303 travel documents require for certificates + and signatures larger than the 255/256-byte short-APDU limit. + + * **Smart Card Reader Compatibility by Country** [`HTML `__] — national eID and professional card compatibility per country, with the official government middleware required for each + * **FIDO2 Card Compatibility — Services and Platforms** [`HTML `__] — which services and operating systems work with a Cryptnox FIDO2 NFC card, second-factor or passwordless, and where extra software is needed + * **Click-to-Tap — FIDO2 User Presence on a Desktop Reader** [`HTML `__] — what the Click-to-Tap button does, why FIDO2 sign-in on a contact reader needs it, its requirements, and troubleshooting .. toctree:: :hidden: @@ -41,14 +43,12 @@ and signatures larger than the 255/256-byte short-APDU limit. fido2-compatibility click-to-tap +.. only:: html -------------------------- - - -Other resources -=============== + Other resources + =============== -* `Cryptnox Product Documentation `_ -* `Cryptnox Website `_ -* `Cryptnox on GitHub `_ -* `Contact Cryptnox `_ + * `Cryptnox Product Documentation `_ + * `Cryptnox Website `_ + * `Cryptnox on GitHub `_ + * `Contact Cryptnox `_ diff --git a/requirements.txt b/requirements.txt index 5091075..6f5d224 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,5 @@ sphinx sphinx-rtd-theme sphinx-sitemap +cairosvg +pillow