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

Aperta
  • Qualcosa non va?
#115 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
12/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
markdown, python
Ambito
devtools, documentation

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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.
Lingua principale
Python
Stelle
0
Fork
0
Merge medio
6h 14m
PR unite (30g)
27

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di AbsaOSS/living-doc

Tutte le issue di AbsaOSS/living-doc

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.