PDF output: `living-doc-generator-pdf` on the shared contracts

Open
#115 0 comments 0 reactions 0 assignees View on GitHub

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

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

type:epic
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-pdf renders technical-project, ui-test-catalog and coverage-matrix from living-doc-toolkit
    outputs read through read_artifact, in both views, with no vendored schema.
  • One presentation model for both generators: the view rules move from generator-markdown into
    living-doc-utilities, and both generators render that model. A generator-markdown caller 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's action.yml: Python ≥ 3.10 from PATH with a
    one-line error below it, its own venv under $RUNNER_TEMP, a runtime-only requirements.txt, and a
    verbose-logging input. It also gets a local-integration.sh and 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 next living-doc release.
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's presentation.py into utilities as one public function, released as a minor.
  • living-doc-generator-markdown: renders utilities' presentation model and deletes its own; its golden snapshots
    stay byte-identical.
  • living-doc-generator-pdf: the composite action in the fleet shape. It copies generator-markdown's venv step,
    renames verbose to verbose-logging, and splits requirements.txt (runtime only) from requirements-dev.txt.
    README.md lists WeasyPrint's system libraries. Three integration jobs, as in generator-markdown: venv
    isolation, a rebuild when Python changes, and rejection of Python 3.9.
  • living-doc-generator-pdf: inputs on the contracts. Delete generator/schemas/, Draft7Validator,
    version_compat.py and generator/utils/decorators.py, and read each document type's one contract through
    read_artifact. A wrong contract gives CONTRACT_MISMATCH, an invalid file SCHEMA_VALIDATION_FAILED, and a
    raw ui-tests.json given for ui-test-catalog fails with a pointer to normalize-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 equals generator-markdown's for the same input. A missing
    key gives TEMPLATE_KEY_MISSING, and a nested bullet item renders as a nested list.
  • living-doc-generator-pdf: local-integration.sh, by generator-markdown's conventions (.env.local, --check,
    explicit inputs, its own venv, no CI).
  • living-doc-generator-pdf: documentation by the fleet's page rules (copy generator-markdown's
    DEVELOPER.md § Writing documentation and tests/docs/). Two fixes ride along. The release-notes presence
    check's title gains the ## , so a PR body that mentions "release notes" above its own section stops failing.
    The glossary link moves to docs/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 a generator-pdf pin, 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.md and 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-doc release.
Related / References
  • living-doc-generator-markdown DEVELOPER.md § Design rules (presentation module, run report and render manifest,
    URL and HTML safety), action.yml, docs/action.md.
  • living-doc-utilities docs/contracts/rendering.md, docs/authoring/urls-and-html.md.
  • living-doc docs/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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from AbsaOSS/living-doc

All issues in AbsaOSS/living-doc

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.