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