Repository navigation
PDF style: zdocs.sty, need cards and tables in the PDF (3/3) - #23
Open
tobiaskaestner wants to merge 5 commits into
Open
tobiaskaestner wants to merge 5 commits into
tobiaskaestner wants to merge 5 commits into
Conversation
volker-kempert
approved these changes
Oct 29, 2026
The LaTeX preamble was strings in zdocs_conf. It is now a style file,
sphinx/_latex/zdocs.sty, that Sphinx copies next to the .tex and that
the preamble loads after Sphinx's own package. zdocs_conf only sets the
values of the build with \zdsetup{title, version, footer}.
A consumer can give its own style file: configure(latex_style=...). The
PDF loads it last, so it can set the same keys, colors and fonts again.
zdocs.sty loads no package that a Sphinx xelatex build does not load.
It changes the layout only through what Sphinx documents: the page
styles "normal" and "plain" and \sphinxtableofcontents.
Changes in the PDF:
- one font family: the body text uses the sans-serif font of the
headings (FreeSans), not FreeSerif;
- the running header gives the title and the version, not the doc id;
- the footer says "Copyright <year> <holder>", without "All rights
reserved";
- the contents follow the title page under a section-size heading, and
the text starts on the same page (no fncychap, no roman page numbers),
so the page count in the footer is right.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
CSS does not reach LaTeX, so in a PDF a zdocs card was the sphinx-needs
table: grey bands, the fields before the text, labels that look like
the values ("Tags:detection"), and an empty line before the links.
In a LaTeX build, need_cards now replaces the table of each zdocs card
with a zd_need node and writes it with new macros of zdocs.sty
(zdneed, \zdneedhead, \zdneedtitle, \zdneedfield):
- no background, so the card prints well: a bar on the left in the
accent color of the type (the same OKLCH rule as --zd-accent);
- the head: type, ID and the status as a framed badge in the color of
the HTML pill (good, bad, gap, none, or the type accent);
- the title in bold, then the text, then the fields and links;
- each field and link with a grey label in one aligned column;
- a long ID also breaks after an underscore;
- the card breaks across pages (framed, which Sphinx loads already).
The label of the need stays at the top of the card, so links into the
card, and between the PDFs of the set, keep their target.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
In a PDF, a needtable without :colwidths: had the fixed widths of sphinx-needs (15 parts for the title, 5 for each other column): the need IDs broke in two, and long tags and Kconfig names ran past the edge of the page. A table of 30 rows or fewer was a tabular, which does not break across pages: a long one moved to the next page and left an empty page. The new extension pdf_tables gives each such table, in a LaTeX build: - column widths from the content: each column as wide as its longest word (a need ID stays on one line), the rest of the line to the columns with the most text; - the class longtable, so it breaks across pages; - ragged-right cells (class zd-needtable); - a smaller font and less padding (zd-table-small, zd-table-smaller) for a table with too many columns for the line; - a line break after a slash, and after a dot before a letter. zdocs.sty: in a table and in a need card, a line can break after an underscore (penalty 100, so TeX still breaks at a space if it can); in the text of a page a name stays one word. A tabulary column is at least 5.5em wide. The toolbox test report: 960 overfull lines -> 2, 50 pages -> 37. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
The Sphinx title page had the title, "Release <version>", the author
and the date, right-aligned on an otherwise empty page.
zdocs.sty defines \sphinxmaketitle again: the title and the version,
then the document ID, the date and the author. If the PDF links to
other PDFs of its set, the title page names their files and says that
the links work only while the files are in one folder with these names.
zdocs_conf gives the values: \zdsetup{docid, set}.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
ADR 0014: the PDF layout is a LaTeX package that changes Sphinx only through its documented hooks, loads no package that Sphinx does not load, and that a consumer's style file can change. A how-to for a consumer's style file (configure(latex_style=...), the \zdsetup keys, colors, fonts, the label width of a card), the card in a PDF in the directives reference, and pdf_tables in the API reference. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Tobias Kaestner <tobias.kaestner@inovex.de>
tobiaskaestner
force-pushed
the
tkaestner/pdf-set
branch
from
October 29, 2026 11:09
e17ca3f to
33c250c
Compare
tobiaskaestner
force-pushed
the
tkaestner/pdf-style
branch
from
October 29, 2026 11:09
2e7dafd to
5bc5def
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The third of three stacked PRs for the PDF output (base: #22). The PDF layout and style, round 1.
zdocs.sty. The LaTeX preamble was strings in zdocs_conf. It is now a style file,
sphinx/_latex/zdocs.sty, that the preamble loads after Sphinx's own package. zdocs_conf only sets the values with\zdsetup{title, version, footer, docid, set}. A consumer can add its own style file withconfigure(latex_style=...). The PDF loads it last, so it can change the same keys, colors and fonts. zdocs.sty loads no package that a Sphinx xelatex build does not load, and it changes Sphinx only through its documented hooks.Page frame. One font family (FreeSans for body and headings). The running header shows the title and the version, not the doc id. The footer says "Copyright ", without "All rights reserved". The contents come after the title page under a section heading, and the text starts on the same page.
Title page. The title and the version, then the document ID, the date and the author. If the PDF links to other PDFs of its set, the title page lists their files and tells the reader to keep them in one folder with these names.
Need cards in the PDF. CSS does not reach LaTeX, so a card was the sphinx-needs table: grey bands, the fields before the text, and labels that look like values. In a LaTeX build, need_cards now writes each zdocs card with new macros: a bar on the left in the type accent color (no fill, so it prints well), a head with type, ID and a status badge in the pill color, the title in bold, the text, then the fields and links with grey labels in one aligned column. The card can break across pages. The label of the need stays at the top, so links into the card keep their target.
New extension pdf_tables. A needtable without
:colwidths:gets column widths from its content (a need ID stays on one line), the class longtable (it breaks across pages), ragged-right cells, and a smaller font when it has many columns. A line can break after a slash, and after a dot before a letter. In tables and cards, a line can also break after an underscore. In the body text a name stays one word.Docs. ADR 0014 and a how-to for a consumer's style file. The directives reference describes the card in a PDF. pdf_tables is in the API reference.
Checks: unit 556, zdocs docs 0 warnings. safety-toolbox set: requirements 14 -> 10 pages, test specification 16 -> 14, test report 59 -> 35, API traceability 5 -> 4. 0 undefined references, 0 broken links in the set, 2 overfull lines left (an 8-column table in the test report). The matching acceptance changes (header without doc id, title page) come in a separate zdocs-tests PR.
Known open items for round 2: 3-digit page numbers in the contents, ragged-right card fields for long link lists, long URLs in tables, the two link styles, the heading color, and the test report as one table per test case.
🤖 Generated with Claude Code