Skip to content

Give the PDF the same cover and layout as the other manuals #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
embarquech merged 1 commit into from
Sep 16, 2026
Merged

Give the PDF the same cover and layout as the other manuals #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
112 changes: 107 additions & 5 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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'
Expand Down Expand Up @@ -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
''',
}
54 changes: 27 additions & 27 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,30 +7,32 @@
Cryptnox Smart Card Readers
============================

`Download this documentation as a PDF <https://docs.cryptnox.com/cryptnox-readers/cryptnox-readers.pdf>`__
.. only:: html

`Download this documentation as a PDF <https://docs.cryptnox.com/cryptnox-readers/cryptnox-readers.pdf>`__

Compatibility guides
====================

.. raw:: html
Compatibility guides
====================

<div class="card-icon">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<rect x="7" y="2" width="10" height="7" rx="1"/>
<rect x="2" y="11" width="20" height="9" rx="2"/>
<line x1="7" y1="15.5" x2="17" y2="15.5"/>
</svg>
</div>
.. 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.
<div class="card-icon">
<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<rect x="7" y="2" width="10" height="7" rx="1"/>
<rect x="2" y="11" width="20" height="9" rx="2"/>
<line x1="7" y1="15.5" x2="17" y2="15.5"/>
</svg>
</div>

* **Smart Card Reader Compatibility by Country** [`HTML <https://docs.cryptnox.com/cryptnox-readers/reader-compatibility.html>`__] — national eID and professional card compatibility per country, with the official government middleware required for each
* **FIDO2 Card Compatibility — Services and Platforms** [`HTML <https://docs.cryptnox.com/cryptnox-readers/fido2-compatibility.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 <https://docs.cryptnox.com/cryptnox-readers/click-to-tap.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 <https://docs.cryptnox.com/cryptnox-readers/reader-compatibility.html>`__] — national eID and professional card compatibility per country, with the official government middleware required for each
* **FIDO2 Card Compatibility — Services and Platforms** [`HTML <https://docs.cryptnox.com/cryptnox-readers/fido2-compatibility.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 <https://docs.cryptnox.com/cryptnox-readers/click-to-tap.html>`__] — what the Click-to-Tap button does, why FIDO2 sign-in on a contact reader needs it, its requirements, and troubleshooting

.. toctree::
:hidden:
Expand All @@ -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 <https://docs.cryptnox.com/>`_
* `Cryptnox Website <https://www.cryptnox.com>`_
* `Cryptnox on GitHub <https://github.com/cryptnox>`_
* `Contact Cryptnox <https://cryptnox.com/contact/>`_
* `Cryptnox Product Documentation <https://docs.cryptnox.com/>`_
* `Cryptnox Website <https://www.cryptnox.com>`_
* `Cryptnox on GitHub <https://github.com/cryptnox>`_
* `Contact Cryptnox <https://cryptnox.com/contact/>`_
2 changes: 2 additions & 0 deletions requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
sphinx
sphinx-rtd-theme
sphinx-sitemap
cairosvg
pillow
Loading