From f9610cc5fe0e0f8325de7ed5f481ef64b8b2086b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 21 Oct 2026 09:25:54 +0000 Subject: [PATCH] A poster's layout goes with its words: orientation in the front matter, and the page order written down examples/poster/landscape.md now says orientation: landscape itself, so py-doc poster poster/landscape.md builds the landscape poster it is written for, not a portrait one. py-doc.yml keeps the company's look. The posters chapter says which settings go where, and how a poster is laid out from the top down: header, stats and abstract, bands of full-width sections and columns, summary and references, footer. Also splits a 40-word sentence from the barcode docs, which fails the docs lint on main. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01MSgoaW6yVJY8XteKGYy9GB --- docs/guide/12_posters.md | 29 +++++++++++++++++++++++++++-- examples/README.md | 2 +- examples/poster/landscape.md | 1 + examples/py-doc.yml | 3 +-- tests/test_poster.py | 5 +++++ 5 files changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/guide/12_posters.md b/docs/guide/12_posters.md index 1254068..f18916e 100644 --- a/docs/guide/12_posters.md +++ b/docs/guide/12_posters.md @@ -29,7 +29,7 @@ The examples in `examples/poster/` show four kinds, and `examples/py-doc.yml` li | Example | What it shows | |---|---| | `poster.md` | Portrait A1 in the default theme: a picture, a Mermaid diagram, bar and line charts, segments, flow, lanes and `lcd` screens. Also a timeline, a JSON code block and a full-width section. A QR code is in the footer. Every setting is in its front matter | -| `landscape.md` | Landscape A1 in three columns, in the theme of a made-up company, with its web fonts inside the page (`embed_fonts: [latin]`) and a partner logo in the footer. A numbered Mermaid sequence from `diagrams.mermaid`, a gallery of mounting drawings, an acceptance checklist, handover steps, a QR block and an included table. The words are in the Markdown and the look (orientation, theme, header, footer) is in `py-doc.yml` | +| `landscape.md` | Landscape A1 in three columns, in the theme of a made-up company, with its web fonts inside the page (`embed_fonts: [latin]`) and a partner logo in the footer. A numbered Mermaid sequence from `diagrams.mermaid`, a gallery of mounting drawings, an acceptance checklist, handover steps, a QR block and an included table. The words and the layout (orientation, paper) are in the front matter, and the company's look (theme, header, footer) is in `py-doc.yml` | | `release.md` | Portrait A3 in the dark theme: a column chart with two series, a before and after `compare` and a Mermaid sequence with notes. Also title cards, a vertical timeline, callouts, `people`, references and a `{{version}}` variable | | `reliability.md` | Portrait A0 in the print theme, in three columns set by `columns` and `split`, with the logo on the right and `version: git`. PlantUML, Graphviz, Vega-Lite and ditaa (PNG) diagrams, a `figure` block, a line chart with `max`, `height` and `colours`, `highlight` figures, `progress` bars, `[[INCLUDE:]]`, `[[INCLUDE-CODE:]]`, `[[IF:]]` and `[[NOT:]]` with `conditions` from `py-doc.yml`, and table and figure captions | @@ -42,6 +42,8 @@ Every setting can be written in four places. Each one wins over the ones before 1. The poster's entry under `posters:` in `py-doc.yml`. 1. The command line: `--theme`, `--var` and `--condition`. +Put a setting with what it belongs to. The layout goes with the words, so `orientation`, `columns`, `split`, `paper` and `width` belong in the front matter: the file then builds the same poster on its own, with `py-doc poster file.md`. The company's look is shared, so its `theme`, `colours`, `logo`, `header` and `footer` belong under `poster:` in `py-doc.yml`. The poster's entry is for what one poster does differently, and the command line is for one build. + Mappings such as `colours` and `footer` are merged key by key, so a poster can change one colour and keep the rest. A path is relative to the file that names it. That is `py-doc.yml` for the first and third places, the Markdown file for the front matter, and the working folder for the command line. ```yaml @@ -92,6 +94,29 @@ A mistake in `py-doc.yml`, such as an unknown key or a mapping where a value sho ## Page structure +A poster is laid out from the top down, always in this order: + +1. **Header**: `title`, `subtitle`, `byline` and `logo` from the settings. Without a title, the first `#` heading is the title. +1. **Stats** and **abstract**: `## Stats` and `## Abstract`, full width, wherever they are in the file. +1. **The bands**, in the order of the sections. A section whose heading ends in `{.wide}` is a full-width band of its own. The sections between two wide ones are a band of columns, balanced by height. +1. **Summary** and **references**: `## Summary` and `## References`, full width, wherever they are in the file. +1. **Footer**: from the `footer` setting, full width at the bottom. + +So a poster that goes full width, two columns, full width, two columns, full width is written as: + +```markdown +## 1. Overview {.wide} +## 2. Left of the first band +## 3. Right of the first band +## 4. Results {.wide} +## 5. Left of the second band +## 6. Right of the second band +## 7. Next steps {.wide} +## Summary +``` + +`columns:` sets how many columns every band of columns has. + | Heading | Becomes | |---|---| | `## Stats` | A table of value, label, and optionally a change and a verdict, shown as the strip of figures. The header row is ignored | @@ -275,7 +300,7 @@ SN-100-0042 ``` ```` -- The check digit of an EAN, UPC or ITF-14 code is worked out when it is left out, and checked when it is given, so a mistyped digit stops the build instead of printing a barcode of another product. Spaces and hyphens in the digits are ignored. +- The check digit of an EAN, UPC or ITF-14 code is worked out when it is left out, and checked when it is given. So a mistyped digit stops the build instead of printing a barcode of another product. Spaces and hyphens in the digits are ignored. - EAN and UPC are drawn as on products: longer guard bars, and the digits in their groups between them. The space the scanner needs on each side (the quiet zone) is part of the drawing, so nothing should be put closer than its white box. - `width=` is the whole drawing, quiet zones included. Print a retail code no smaller than its standard size: about 140 pixels wide for EAN-13 and UPC-A, 100 for EAN-8 and 400 for ITF-14. diff --git a/examples/README.md b/examples/README.md index 766efec..20ed8a8 100644 --- a/examples/README.md +++ b/examples/README.md @@ -43,7 +43,7 @@ What needs Docker: Word, PowerPoint, PDF and HTML output, every diagram type, dr | `docs/release-notes.md` | A short document whose version comes from Git (`version: git`) | | `docs/interfaces.md` | Interface specifications for a sample library system (OpenAPI, AsyncAPI, gRPC and GraphQL), each included from its own file in `docs/includes/apis/`, and a PlantUML use case diagram | | `docs/deck/slides.md` | The deck: section slides, bullets, columns, incremental lists, both kinds of speaker notes, diagrams, a picture, a table, maths, callouts, code, an include, a condition, a page break | -| `poster/` | Four one-page HTML posters, listed under `posters:` in `py-doc.yml`. Between them they use every poster setting and block. `poster.md` is portrait in the default theme, with a picture, a Mermaid diagram, charts, the poster blocks and a QR code, all set in its front matter. `landscape.md` has only the words: its orientation, theme (`brand/example-instruments.yml`, a made-up company with its logo), embedded fonts, header and footer are in `py-doc.yml`, and it has a gallery and steps. `release.md` uses the dark theme, a two-series chart and a `{{version}}` variable. `reliability.md` is a three-column A0 report in the print theme, with PlantUML, Graphviz, Vega-Lite and ditaa, includes, conditions and `version: git`. They are outside `docs/` because a poster is not a chapter of the guide | +| `poster/` | Four one-page HTML posters, listed under `posters:` in `py-doc.yml`. Between them they use every poster setting and block. `poster.md` is portrait in the default theme, with a picture, a Mermaid diagram, charts, the poster blocks and a QR code, all set in its front matter. `landscape.md` has the words and the layout (`orientation: landscape`) in its front matter. The company's look is in `py-doc.yml`: its theme (`brand/example-instruments.yml`, a made-up company with its logo), embedded fonts, header and footer. It has a gallery and steps. `release.md` uses the dark theme, a two-series chart and a `{{version}}` variable. `reliability.md` is a three-column A0 report in the print theme, with PlantUML, Graphviz, Vega-Lite and ditaa, includes, conditions and `version: git`. They are outside `docs/` because a poster is not a chapter of the guide | | `docs/includes/` | Files pulled in with `[[INCLUDE:]]` and `[[INCLUDE-CODE:]]` | | `templates/sensor.docx` | The Word template: logo, title page with `Replace-with-*` placeholders, header, footer with page numbers, callout styles, a `Lead Paragraph` style, `[[INSERTCONTENT]]` where the body goes | | `templates/sensor_Draft.docx` | The same template with a red "DRAFT" header. A document with `status: Draft` uses it without being told to | diff --git a/examples/poster/landscape.md b/examples/poster/landscape.md index a92b6c8..34950b0 100644 --- a/examples/poster/landscape.md +++ b/examples/poster/landscape.md @@ -2,6 +2,7 @@ title: Commissioning an SN-100 network subtitle: From an empty building to readings on the dashboard in one day byline: Example Instruments field engineering +orientation: landscape # the sections are written for three columns, so the layout goes with the words paper: a1 --- diff --git a/examples/py-doc.yml b/examples/py-doc.yml index 838076a..ca6334e 100644 --- a/examples/py-doc.yml +++ b/examples/py-doc.yml @@ -202,10 +202,9 @@ posters: sensor-node: source: poster/poster.md # every setting is in its front matter commissioning: - source: poster/landscape.md # its front matter has the words; the look is set here + source: poster/landscape.md # its front matter has the words and the layout; the company's look is set here output: build/posters/commissioning.html pdf: true # and build/posters/commissioning.pdf, one A1 landscape page - orientation: landscape theme: poster/brand/example-instruments.yml colours: accent: "#d9573a" # one colour changed over the theme diff --git a/tests/test_poster.py b/tests/test_poster.py index e559de5..0110f56 100644 --- a/tests/test_poster.py +++ b/tests/test_poster.py @@ -264,6 +264,11 @@ def test_the_example_posters_build(drawn, monkeypatch, name, title): assert "image not found" not in page and "](" not in page.split("", 1)[1], "every picture and link is embedded or rendered" +def test_an_example_poster_built_on_its_own_has_the_layout_it_was_written_for(drawn): + page, _ = build(EXAMPLES / "landscape.md", lambda: object()) # as py-doc poster poster/landscape.md does + assert 'class="poster landscape"' in page and "size:841mm 594mm" in page + + def test_the_reliability_example_uses_its_includes_and_conditions(drawn, monkeypatch): monkeypatch.setattr("py_doc.poster.git_version", lambda folder: "v1.0-3-gabc1234") page, _ = build(EXAMPLES / "reliability.md", lambda: object(), {"conditions": {"internal": True}})