PDF output: `living-doc-generator-pdf` on the shared contracts
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 12/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Tech stack
- markdown, python
- Domain
- devtools, documentation
Research direction
This is an epic, so start with its first subtask: moving the view rules from generator_markdown/presentation.py into living-doc-utilities as one public function, specified in docs/contracts/rendering.md. Read that module and the contract first, then confirm the golden snapshots in living-doc-generator-markdown stay byte-identical. Done means that subtask's checklist passes and the minor release is cut.
Written by the indexing model from the issue text.
Description
Background
living-doc v0.1.0 renders Markdown only. living-doc-generator-pdf on master (4ce33c3, no tag) is still the
pre-contract generator. It imports nothing from living_doc_utilities. It vendors four schemas under generator/schemas/
and validates with Draft7Validator, and it fetches the image URLs that authors write. Its action installs into the
runner's interpreter. In living-doc, docs/projects/generator-pdf.md and the two PDF tutorials
(docs/tutorials/gh-source-to-pdf.md, docs/tutorials/technical-project-to-pdf.md) are marked planned and carry no
workflow.
living-doc-generator-markdown v0.1.0 already implements the view rules (utilities docs/contracts/rendering.md)
in one module, generator_markdown/presentation.py, which maps an input and its view to a presentation model that
the templates only render. Its run report carries a render manifest: the entity ids, AC ids, aspects and badges per
view. Both were built so that a second generator renders the same model instead of implementing the rules again
(generator-markdown DEVELOPER.md § Design rules).
Goals
generator-pdfrenderstechnical-project,ui-test-catalogandcoverage-matrixfromliving-doc-toolkit
outputs read throughread_artifact, in both views, with no vendored schema.- One presentation model for both generators: the view rules move from
generator-markdowninto
living-doc-utilities, and both generators render that model. Agenerator-markdowncaller sees no change.
Parity between the two outputs is render-manifest equality. - No fetch outside the template directory; the shared URL policy and no raw HTML in any emitted field, tested with
hostile content. - The action has the fleet shape, copied from
generator-markdown'saction.yml: Python ≥ 3.10 fromPATHwith a
one-line error below it, its own venv under$RUNNER_TEMP, a runtime-onlyrequirements.txt, and a
verbose-logginginput. It also gets alocal-integration.shand documentation that follows the fleet's page rules. - PDF joins the chain in
living-doc: the local integration runner, a milestone run over the testbed, the two
tutorials with a workflow run by tag, and the nextliving-docrelease.
Subtasks
In landing order. Each child is drafted when the previous one has merged, against the code as it is then.
-
living-doc-utilities: the presentation model (views × fields, badges, grouping) moves from
generator-markdown'spresentation.pyintoutilitiesas one public function, released as a minor. -
living-doc-generator-markdown: rendersutilities' presentation model and deletes its own; its golden snapshots
stay byte-identical. -
living-doc-generator-pdf: the composite action in the fleet shape. It copiesgenerator-markdown's venv step,
renamesverbosetoverbose-logging, and splitsrequirements.txt(runtime only) fromrequirements-dev.txt.
README.mdlists WeasyPrint's system libraries. Three integration jobs, as ingenerator-markdown: venv
isolation, a rebuild when Python changes, and rejection of Python 3.9. -
living-doc-generator-pdf: inputs on the contracts. Deletegenerator/schemas/,Draft7Validator,
version_compat.pyandgenerator/utils/decorators.py, and read each document type's one contract through
read_artifact. A wrong contract givesCONTRACT_MISMATCH, an invalid fileSCHEMA_VALIDATION_FAILED, and a
rawui-tests.jsongiven forui-test-catalogfails with a pointer tonormalize-tests. Fetch safety: no fetch
outside the template directory and the shared URL policy, tested both through the filter and with HTML that
bypasses it (a loopback probe, a relative path that escapes, a symlink,javascript:, a protocol-relative link). -
living-doc-generator-pdf: templates render the shared presentation model in both views. The run report counts
come from the input model, and its render manifest equalsgenerator-markdown's for the same input. A missing
key givesTEMPLATE_KEY_MISSING, and a nested bullet item renders as a nested list. -
living-doc-generator-pdf:local-integration.sh, bygenerator-markdown's conventions (.env.local,--check,
explicit inputs, its own venv, no CI). -
living-doc-generator-pdf: documentation by the fleet's page rules (copygenerator-markdown's
DEVELOPER.md§ Writing documentation andtests/docs/). Two fixes ride along. The release-notes presence
check'stitlegains the##, so a PR body that mentions "release notes" above its own section stops failing.
The glossary link moves todocs/reference/glossary.md#id-uniqueness; the old guide path is a redirect without
that fragment. -
living-doc: PDF in the chain. The runner renders PDF beside Markdown with agenerator-pdfpin, a pin-report
row and the retired-names check. The two PDF tutorials get their workflow, run once by tag.
docs/projects/generator-pdf.md,guides/build-a-pipeline.mdand the planned lines lose "planned". - Release: tag
generator-pdf, run a milestone over the testbed with PDF output, and list the tag in the next
living-docrelease.
Related / References
living-doc-generator-markdownDEVELOPER.md§ Design rules (presentation module, run report and render manifest,
URL and HTML safety),action.yml,docs/action.md.living-doc-utilitiesdocs/contracts/rendering.md,docs/authoring/urls-and-html.md.living-docdocs/projects/generator-pdf.md,docs/tutorials/gh-source-to-pdf.md,
docs/tutorials/technical-project-to-pdf.md,docs/_integration/README.md.- Not in this epic: performance at volume (WeasyPrint over thousands of entities) is its own issue; so are Windows
runners and the manual link-check run, which the fleet tracks per repository.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 14m
- Merged PRs (30d)
- 27
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from AbsaOSS/living-doc
-
type:tech-debt
Difficulty 1/5 Under an hour Newbie friendliness 78/100
AbsaOSS/living-doc#133 ·
Maintainers usually reply within 1 day
-
type:tech-debt
Difficulty 1/5 1-3 hours Newbie friendliness 85/100
AbsaOSS/living-doc#130 ·
Maintainers usually reply within 1 day
-
type:tech-debt
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
AbsaOSS/living-doc#129 ·
Maintainers usually reply within 1 day
-
type:tech-debt
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
AbsaOSS/living-doc#119 ·
Maintainers usually reply within 1 day
-
type:tech-debt
Difficulty 5/5 Over a week Newbie friendliness 5/100
AbsaOSS/living-doc#136 ·
Maintainers usually reply within 1 day
All issues in AbsaOSS/living-doc
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
deepchem/deepchem#5289 · 1 comment ·
Maintainers usually reply within 2 days
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 60/100
UKGovernmentBEIS/inspect_evals#2892 · 1 comment ·
Maintainers usually reply within 1 day
-
Versioning docs: say that no output from the 0.46 warning check means nothing is affectedPossibly taken @grelinfo claimed this today. Opendocumentation priority:low size:S
Difficulty 1/5 Under an hour Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
alphacrack/readme2demo#293 ·