documentation-checker 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. documentation_checker/__init__.py +9 -0
  2. documentation_checker/__main__.py +7 -0
  3. documentation_checker/audit/__init__.py +7 -0
  4. documentation_checker/audit/accessibility.py +481 -0
  5. documentation_checker/audit/engine.py +136 -0
  6. documentation_checker/audit/images.py +416 -0
  7. documentation_checker/audit/links.py +224 -0
  8. documentation_checker/audit/prose.py +475 -0
  9. documentation_checker/audit/sides.py +234 -0
  10. documentation_checker/audit/spelling.py +433 -0
  11. documentation_checker/audit/structure.py +864 -0
  12. documentation_checker/audit/style.py +208 -0
  13. documentation_checker/audit/text.py +428 -0
  14. documentation_checker/audit/typography.py +597 -0
  15. documentation_checker/cli.py +413 -0
  16. documentation_checker/compare/__init__.py +2 -0
  17. documentation_checker/compare/aggregate.py +234 -0
  18. documentation_checker/compare/align.py +1062 -0
  19. documentation_checker/compare/classify.py +452 -0
  20. documentation_checker/compare/drafts.py +161 -0
  21. documentation_checker/compare/engine.py +833 -0
  22. documentation_checker/compare/images.py +1007 -0
  23. documentation_checker/compare/links.py +370 -0
  24. documentation_checker/compare/structure.py +376 -0
  25. documentation_checker/compare/textdiff.py +369 -0
  26. documentation_checker/compare/verdicts.py +185 -0
  27. documentation_checker/config.py +736 -0
  28. documentation_checker/errors.py +18 -0
  29. documentation_checker/extract/__init__.py +6 -0
  30. documentation_checker/extract/common.py +387 -0
  31. documentation_checker/extract/html/__init__.py +6 -0
  32. documentation_checker/extract/html/chrome.py +46 -0
  33. documentation_checker/extract/html/css.py +87 -0
  34. documentation_checker/extract/html/dom.py +762 -0
  35. documentation_checker/extract/html/facts.py +374 -0
  36. documentation_checker/extract/html/images.py +511 -0
  37. documentation_checker/extract/html/links.py +379 -0
  38. documentation_checker/extract/html/loader.py +616 -0
  39. documentation_checker/extract/html/ordering.py +167 -0
  40. documentation_checker/extract/html/profiles.py +291 -0
  41. documentation_checker/extract/html/site.py +225 -0
  42. documentation_checker/extract/loader.py +93 -0
  43. documentation_checker/extract/pdf/__init__.py +6 -0
  44. documentation_checker/extract/pdf/blocks.py +747 -0
  45. documentation_checker/extract/pdf/catalog.py +52 -0
  46. documentation_checker/extract/pdf/chrome.py +778 -0
  47. documentation_checker/extract/pdf/figures.py +1113 -0
  48. documentation_checker/extract/pdf/headings.py +339 -0
  49. documentation_checker/extract/pdf/joining.py +323 -0
  50. documentation_checker/extract/pdf/kinds.py +312 -0
  51. documentation_checker/extract/pdf/layout.py +334 -0
  52. documentation_checker/extract/pdf/loader.py +1140 -0
  53. documentation_checker/extract/pdf/reader.py +2059 -0
  54. documentation_checker/extract/pdf/segments.py +248 -0
  55. documentation_checker/extract/pdf/table_blocks.py +784 -0
  56. documentation_checker/extract/pdf/table_process.py +292 -0
  57. documentation_checker/extract/pdf/table_work.py +559 -0
  58. documentation_checker/extract/pdf/tables.py +549 -0
  59. documentation_checker/extract/pdf/tags.py +838 -0
  60. documentation_checker/images/__init__.py +2 -0
  61. documentation_checker/images/hashing.py +181 -0
  62. documentation_checker/images/load.py +737 -0
  63. documentation_checker/images/metrics.py +581 -0
  64. documentation_checker/images/objects.py +111 -0
  65. documentation_checker/images/pixels.py +330 -0
  66. documentation_checker/images/refs.py +285 -0
  67. documentation_checker/images/streams.py +371 -0
  68. documentation_checker/images/svg.py +344 -0
  69. documentation_checker/images/thumbnail.py +73 -0
  70. documentation_checker/model/__init__.py +2 -0
  71. documentation_checker/model/document.py +348 -0
  72. documentation_checker/model/facts.py +146 -0
  73. documentation_checker/model/findings.py +217 -0
  74. documentation_checker/pipeline.py +442 -0
  75. documentation_checker/report/__init__.py +2 -0
  76. documentation_checker/report/context.py +530 -0
  77. documentation_checker/report/html.py +152 -0
  78. documentation_checker/report/markdown.py +350 -0
  79. documentation_checker/report/templates/report.css +301 -0
  80. documentation_checker/report/templates/report.html.j2 +170 -0
  81. documentation_checker/report/templates/report.js +36 -0
  82. documentation_checker/report/templates/report.md.j2 +110 -0
  83. documentation_checker/report/terminal.py +260 -0
  84. documentation_checker/rules.py +429 -0
  85. documentation_checker/spell/__init__.py +2 -0
  86. documentation_checker/spell/data/fr/LICENSE +373 -0
  87. documentation_checker/spell/data/fr/README_dict_fr.txt +67 -0
  88. documentation_checker/spell/data/fr/SOURCE.txt +16 -0
  89. documentation_checker/spell/data/fr/fr-toutesvariantes.aff +6596 -0
  90. documentation_checker/spell/data/fr/fr-toutesvariantes.dic +87073 -0
  91. documentation_checker/spell/dictionary.py +88 -0
  92. documentation_checker/spell/speller.py +412 -0
  93. documentation_checker/spell/words.py +377 -0
  94. documentation_checker/text/__init__.py +2 -0
  95. documentation_checker/text/lang.py +204 -0
  96. documentation_checker/text/lexicon.py +200 -0
  97. documentation_checker/text/normalize.py +229 -0
  98. documentation_checker/text/numbers.py +81 -0
  99. documentation_checker/text/tokenize.py +70 -0
  100. documentation_checker-0.1.0.dist-info/METADATA +1049 -0
  101. documentation_checker-0.1.0.dist-info/RECORD +106 -0
  102. documentation_checker-0.1.0.dist-info/WHEEL +4 -0
  103. documentation_checker-0.1.0.dist-info/entry_points.txt +3 -0
  104. documentation_checker-0.1.0.dist-info/licenses/LICENSE +202 -0
  105. documentation_checker-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md +71 -0
  106. documentation_checker-0.1.0.dist-info/licenses/src/documentation_checker/spell/data/fr/LICENSE +373 -0
@@ -0,0 +1,9 @@
1
+ # Copyright 2026 Christophe Le Douarec
2
+ """Documentation Checker.
3
+
4
+ Compare and audit PDF and HTML documentation.
5
+ """
6
+
7
+ from typing import Final
8
+
9
+ __version__: Final[str] = "0.1.0"
@@ -0,0 +1,7 @@
1
+ # Copyright 2026 Christophe Le Douarec
2
+ """Entry point for ``python -m documentation_checker``."""
3
+
4
+ from documentation_checker.cli import main
5
+
6
+ if __name__ == "__main__":
7
+ main(prog_name="documentation-checker")
@@ -0,0 +1,7 @@
1
+ # Copyright 2026 Christophe Le Douarec
2
+ """Audit of a single document: its structure, its links, its accessibility.
3
+
4
+ `audit_document` of `documentation_checker.audit.engine` runs the families of
5
+ checks that the configuration asks for, and finalizes their drafts as `compare`
6
+ does.
7
+ """
@@ -0,0 +1,481 @@
1
+ # Copyright 2026 Christophe Le Douarec
2
+ """Check the accessibility of a document.
3
+
4
+ A PDF without a structure tree, one that does not declare a tag structure
5
+ or whose catalog has no ``/StructTreeRoot``, is untagged; a tree that was
6
+ read in part, or not at all for another reason, is not. A PDF declares its
7
+ language in its catalog and its title in its metadata; an HTML page, its
8
+ language in the ``lang`` of its ``html`` element, which has to be a
9
+ language tag, and its title in its head. A document that declares French
10
+ or English, but whose prose, its first `LANG_SAMPLE_BLOCKS` blocks of
11
+ `PROSE_KINDS`, plainly reads as the other language, as `strong_language`
12
+ tells, has a language mismatch. The characters of a PDF without a Unicode
13
+ mapping give one finding, at the first page that has some, which is major
14
+ from a share of the characters of the document; each scanned page gives
15
+ one.
16
+
17
+ An image of an HTML page needs an alternative text, an inline SVG a title
18
+ or a label, and an alternative text that is a file name, `FILE_NAME_ALT`,
19
+ says nothing; an empty alternative text marks a decorative image. Each
20
+ ``Figure`` of the structure tree of a PDF needs a ``/Alt`` or an
21
+ ``/ActualText``, and its ``/Alt`` is no file name; each ``Table`` of the
22
+ tree, like each table of the content of an HTML page, needs a header cell.
23
+ The image blocks of a PDF, whose alternative texts the tree holds, are not
24
+ judged by themselves.
25
+
26
+ A link of the content of an HTML page needs a name, and the text of a link
27
+ of a block, or under a link annotation of a PDF, has to tell where the link
28
+ leads: a text of `GENERIC_LINK_TEXTS`, compared by its loose key, does not.
29
+
30
+ The texts of the document that a detail quotes are cut.
31
+ """
32
+
33
+ import re
34
+ from collections import Counter
35
+ from itertools import islice
36
+ from typing import TYPE_CHECKING, Final
37
+
38
+ from documentation_checker.audit.sides import LinkMarks, quote
39
+ from documentation_checker.compare.drafts import Draft, marked_side
40
+ from documentation_checker.images.refs import describe
41
+ from documentation_checker.model.document import BlockKind, SourceRef
42
+ from documentation_checker.model.facts import NO_STRUCTURE_TREE
43
+ from documentation_checker.model.findings import Severity
44
+ from documentation_checker.text.lang import (
45
+ LANG_SAMPLE_BLOCKS,
46
+ LANGUAGE_NAMES,
47
+ declared_language,
48
+ strong_language,
49
+ )
50
+ from documentation_checker.text.normalize import (
51
+ ELLIPSIS,
52
+ loose_key,
53
+ normalize_display,
54
+ printable,
55
+ strict_key,
56
+ )
57
+
58
+ if TYPE_CHECKING:
59
+ from documentation_checker.config import AuditThresholds
60
+ from documentation_checker.model.document import Block, Document
61
+ from documentation_checker.model.facts import HtmlPageFacts, TaggedElement
62
+ from documentation_checker.model.findings import Side
63
+
64
+ FILE_NAME_ALT: Final = re.compile(
65
+ r"(?i)^[\w\-./\\]+\.(?:png|jpe?g|gif|svg|webp|bmp|tiff?|pdf|eps|avif)$",
66
+ )
67
+ GENERIC_LINK_TEXTS: Final = frozenset(
68
+ {
69
+ "click here",
70
+ "here",
71
+ "click",
72
+ "read more",
73
+ "learn more",
74
+ "more",
75
+ "this link",
76
+ "link",
77
+ "this page",
78
+ "cliquez ici",
79
+ "ici",
80
+ "cliquer ici",
81
+ "lire la suite",
82
+ "en savoir plus",
83
+ "ce lien",
84
+ "lien",
85
+ "cette page",
86
+ },
87
+ )
88
+ # The blocks whose text tells the language of a document: headings,
89
+ # paragraphs, items, captions, quotes and admonitions.
90
+ PROSE_KINDS: Final = frozenset(
91
+ {
92
+ BlockKind.HEADING,
93
+ BlockKind.PARAGRAPH,
94
+ BlockKind.LIST_ITEM,
95
+ BlockKind.CAPTION,
96
+ BlockKind.QUOTE,
97
+ BlockKind.ADMONITION,
98
+ },
99
+ )
100
+ UNMAPPED_PAGES_SHOWN: Final = 10
101
+
102
+ _UNTAGGED: Final = "a11y.pdf_untagged"
103
+ _LANG_MISSING: Final = "a11y.lang_missing"
104
+ _LANG_MISMATCH: Final = "a11y.lang_mismatch"
105
+ _TITLE_MISSING: Final = "a11y.title_missing"
106
+ _UNMAPPED: Final = "a11y.unmapped_chars"
107
+ _SCANNED: Final = "a11y.scanned_page"
108
+ _ALT_MISSING: Final = "a11y.alt_missing"
109
+ _ALT_FILENAME: Final = "a11y.alt_filename"
110
+ _SVG_TITLE: Final = "a11y.svg_title"
111
+ _TABLE_HEADERS: Final = "a11y.table_headers"
112
+ _LINK_EMPTY: Final = "a11y.link_empty"
113
+ _LINK_TEXT: Final = "a11y.link_text"
114
+
115
+ _NO_TREE: Final = (
116
+ "the PDF has no structure tree: assistive technologies read it without"
117
+ " headings, lists, tables or figures"
118
+ )
119
+ _FILE_NAME: Final = "file name"
120
+ _SUBTAG: Final = "-"
121
+ _MORE_PAGES: Final = f", {ELLIPSIS}"
122
+
123
+
124
+ def _link_key(text: str) -> str:
125
+ """Return the loose key of the text of a link."""
126
+ counter: Counter[str] = Counter()
127
+ return loose_key(strict_key(normalize_display(text, counter), counter))
128
+
129
+
130
+ def _document_side(doc: Document) -> Side:
131
+ """Return the side of a finding about the whole document.
132
+
133
+ It shows the name of a PDF, or the first page of a site.
134
+ """
135
+ name = doc.parts[0] if doc.format == "html" and doc.parts else ""
136
+ name = name or doc.path.name
137
+ return marked_side(SourceRef(name), printable(name))
138
+
139
+
140
+ def _is_untagged(doc: Document) -> bool:
141
+ """Return whether a PDF has no structure tree.
142
+
143
+ A tree that was not read, or read in part, for another reason, such as
144
+ encryption or a budget, is no proof that the PDF is untagged.
145
+ """
146
+ tags = doc.tags
147
+ return doc.tagged is False or (
148
+ tags is not None and tags.problem == NO_STRUCTURE_TREE
149
+ )
150
+
151
+
152
+ def prose_sample(doc: Document) -> str:
153
+ """Return the prose whose text tells the language of a document.
154
+
155
+ Args:
156
+ doc: The document.
157
+
158
+ Returns:
159
+ The texts of its first `LANG_SAMPLE_BLOCKS` blocks of `PROSE_KINDS`,
160
+ joined by spaces.
161
+ """
162
+ return " ".join(
163
+ islice(
164
+ (block.text for block in doc.blocks if block.kind in PROSE_KINDS),
165
+ LANG_SAMPLE_BLOCKS,
166
+ ),
167
+ )
168
+
169
+
170
+ def _language_mismatch(doc: Document, side: Side) -> Draft | None:
171
+ """Return the draft of a document whose prose reads as another language.
172
+
173
+ Args:
174
+ doc: The audited document.
175
+ side: The side of a finding about the whole document.
176
+
177
+ Returns:
178
+ The draft when the document declares French or English and its
179
+ `prose_sample` plainly reads as the other language; else ``None``.
180
+ """
181
+ declared = doc.declared_lang
182
+ if declared is None:
183
+ return None
184
+ primary = declared.partition(_SUBTAG)[0].casefold()
185
+ if primary not in LANGUAGE_NAMES:
186
+ return None
187
+ found = strong_language(prose_sample(doc))
188
+ if found is None or found == primary:
189
+ return None
190
+ detail = (
191
+ f'the document declares "{quote(declared)}" but its text reads as'
192
+ f" {LANGUAGE_NAMES[found]}"
193
+ )
194
+ return Draft(_LANG_MISMATCH, None, side, None, detail)
195
+
196
+
197
+ def _unmapped(doc: Document, thresholds: AuditThresholds) -> Draft | None:
198
+ """Return the draft of the characters of a PDF without Unicode mapping.
199
+
200
+ Args:
201
+ doc: The PDF.
202
+ thresholds: Thresholds of the audit.
203
+
204
+ Returns:
205
+ One draft at the first page with such characters, which counts them
206
+ and lists the labels of the first `UNMAPPED_PAGES_SHOWN` pages that
207
+ have some; major when they reach ``unmapped_major`` of the
208
+ characters of the document. ``None`` without such characters.
209
+ """
210
+ touched = [page for page in doc.pdf_pages if page.unmapped]
211
+ if not touched:
212
+ return None
213
+ total = sum(page.unmapped for page in touched)
214
+ chars = sum(page.chars for page in doc.pdf_pages)
215
+ labels = ", ".join(
216
+ quote(page.label) for page in touched[:UNMAPPED_PAGES_SHOWN]
217
+ )
218
+ if len(touched) > UNMAPPED_PAGES_SHOWN:
219
+ labels += _MORE_PAGES
220
+ severity = (
221
+ Severity.MAJOR if total >= thresholds.unmapped_major * chars else None
222
+ )
223
+ source = SourceRef(doc.path.name, page=touched[0].number)
224
+ detail = (
225
+ f"{total} of {chars} characters have no Unicode mapping,"
226
+ f" on page(s) {labels}"
227
+ )
228
+ side = marked_side(source, printable(doc.path.name))
229
+ return Draft(_UNMAPPED, severity, side, None, detail)
230
+
231
+
232
+ def _document_drafts(
233
+ doc: Document,
234
+ thresholds: AuditThresholds,
235
+ ) -> list[Draft]:
236
+ """Return the drafts about the whole document.
237
+
238
+ Returns:
239
+ For a PDF, its missing tree, its missing language, a language
240
+ mismatch, its missing title and its unmapped characters; for a site,
241
+ a language mismatch.
242
+ """
243
+ side = _document_side(doc)
244
+ mismatch = _language_mismatch(doc, side)
245
+ if doc.format != "pdf":
246
+ return [] if mismatch is None else [mismatch]
247
+ drafts: list[Draft] = []
248
+ if _is_untagged(doc):
249
+ drafts.append(Draft(_UNTAGGED, None, side, None, _NO_TREE))
250
+ if doc.declared_lang is None:
251
+ detail = "the PDF declares no language"
252
+ drafts.append(Draft(_LANG_MISSING, None, side, None, detail))
253
+ if mismatch is not None:
254
+ drafts.append(mismatch)
255
+ if not doc.title:
256
+ detail = "the PDF has no title in its metadata"
257
+ drafts.append(Draft(_TITLE_MISSING, None, side, None, detail))
258
+ unmapped = _unmapped(doc, thresholds)
259
+ if unmapped is not None:
260
+ drafts.append(unmapped)
261
+ return drafts
262
+
263
+
264
+ def _bare_table(side: Side) -> Draft:
265
+ """Return the draft of a table without a header cell."""
266
+ detail = "the table has no header cell"
267
+ return Draft(_TABLE_HEADERS, None, side, None, detail, "table")
268
+
269
+
270
+ def _html_page_drafts(page: HtmlPageFacts) -> list[Draft]:
271
+ """Return the drafts of an HTML page.
272
+
273
+ Returns:
274
+ Its missing or wrong language, its missing title, then its tables
275
+ without header cell and its links without a name, in order.
276
+ """
277
+ side = marked_side(SourceRef(page.file), printable(page.file))
278
+ drafts: list[Draft] = []
279
+ lang = page.lang or ""
280
+ if not lang.strip():
281
+ detail = "the page declares no language"
282
+ drafts.append(Draft(_LANG_MISSING, None, side, None, detail, "lang"))
283
+ elif declared_language(lang) is None:
284
+ detail = (
285
+ f'the page declares "{quote(lang)}", which is not a language tag'
286
+ )
287
+ drafts.append(Draft(_LANG_MISSING, None, side, None, detail, "lang"))
288
+ if not page.title:
289
+ detail = "the page has no title"
290
+ drafts.append(Draft(_TITLE_MISSING, None, side, None, detail, "title"))
291
+ for spot in page.bare_tables:
292
+ source = SourceRef(page.file, line=spot.line)
293
+ table = marked_side(source, spot.text, kind=BlockKind.TABLE)
294
+ drafts.append(_bare_table(table))
295
+ for spot in page.empty_links:
296
+ link = marked_side(SourceRef(page.file, line=spot.line), spot.text)
297
+ target = quote(spot.text) or '""'
298
+ detail = f"the link to {target} has neither text nor label"
299
+ drafts.append(Draft(_LINK_EMPTY, None, link, None, detail, "empty"))
300
+ return drafts
301
+
302
+
303
+ def _scanned_drafts(doc: Document) -> list[Draft]:
304
+ """Return one draft for each scanned page of a PDF, shown by its label."""
305
+ return [
306
+ Draft(
307
+ _SCANNED,
308
+ None,
309
+ marked_side(
310
+ SourceRef(doc.path.name, page=page.number),
311
+ f"page {quote(page.label)}",
312
+ ),
313
+ None,
314
+ "the page is an image without text",
315
+ "scanned",
316
+ )
317
+ for page in doc.pdf_pages
318
+ if page.scanned
319
+ ]
320
+
321
+
322
+ def _image_draft(block: Block) -> Draft | None:
323
+ """Return the draft of the alternative text of an HTML image, if wrong.
324
+
325
+ Returns:
326
+ For an image without an alternative text, an untitled inline SVG,
327
+ whose format is SVG and which has no name, or else a missing
328
+ alternative text; for one that is a file name, its draft; else
329
+ ``None``. An empty alternative text marks a decorative image.
330
+ """
331
+ image = block.image
332
+ if image is None:
333
+ return None
334
+ side = marked_side(
335
+ block.source,
336
+ describe(image),
337
+ kind=block.kind,
338
+ image=image,
339
+ )
340
+ alt = image.alt
341
+ if alt is None:
342
+ if image.format == "svg" and not image.name:
343
+ detail = "the drawing has no title nor label"
344
+ return Draft(_SVG_TITLE, None, side, None, detail, "svg")
345
+ detail = "the image has no alternative text"
346
+ return Draft(_ALT_MISSING, None, side, None, detail, "img")
347
+ if FILE_NAME_ALT.match(alt):
348
+ detail = f'the alternative text "{quote(alt)}" is a file name'
349
+ return Draft(_ALT_FILENAME, None, side, None, detail, _FILE_NAME)
350
+ return None
351
+
352
+
353
+ def _link_text_draft(side: Side, text: str, key: str) -> Draft:
354
+ """Return the draft of a link whose text tells nothing.
355
+
356
+ Args:
357
+ side: The side of the link.
358
+ text: The text of the link.
359
+ key: Its loose key, a text of `GENERIC_LINK_TEXTS`, which is the
360
+ pattern of the draft.
361
+
362
+ Returns:
363
+ The draft.
364
+ """
365
+ detail = f'the text "{quote(text)}" does not tell where the link leads'
366
+ return Draft(_LINK_TEXT, None, side, None, detail, key)
367
+
368
+
369
+ def _block_drafts(doc: Document) -> list[Draft]:
370
+ """Return the drafts of the blocks, in order.
371
+
372
+ Returns:
373
+ For each block, that of its image, on an HTML page, then that of
374
+ each of its links whose text tells nothing. The text of a link is
375
+ judged first; only a block with a link whose text tells nothing has
376
+ its links placed, as `LinkMarks` does.
377
+ """
378
+ html = doc.format == "html"
379
+ drafts: list[Draft] = []
380
+ for block in doc.blocks:
381
+ if html and block.kind is BlockKind.IMAGE:
382
+ image = _image_draft(block)
383
+ if image is not None:
384
+ drafts.append(image)
385
+ marks: LinkMarks | None = None
386
+ for index, link in enumerate(block.links):
387
+ key = _link_key(link.text)
388
+ if key not in GENERIC_LINK_TEXTS:
389
+ continue
390
+ marks = marks or LinkMarks(block, [o.text for o in block.links])
391
+ drafts.append(_link_text_draft(marks.side(index), link.text, key))
392
+ return drafts
393
+
394
+
395
+ def _tagged_draft(doc: Document, element: TaggedElement) -> Draft | None:
396
+ """Return the draft of a figure or a table of the structure tree.
397
+
398
+ Returns:
399
+ For a figure without a ``/Alt`` nor an ``/ActualText`` that is not
400
+ blank, a missing alternative text; for one whose ``/Alt`` is a file
401
+ name, that draft; for a table without a ``TH``, a missing header.
402
+ The side shows the type of the element, or the file name, at its
403
+ page.
404
+ """
405
+ source = SourceRef(doc.path.name, page=element.page)
406
+ if element.role == "table" and not element.headers:
407
+ return _bare_table(
408
+ marked_side(source, element.type, kind=BlockKind.TABLE),
409
+ )
410
+ if element.role != "figure":
411
+ return None
412
+ alt = (element.alt or "").strip()
413
+ if not alt and not (element.actual or "").strip():
414
+ side = marked_side(source, element.type, kind=BlockKind.IMAGE)
415
+ detail = "the figure has no alternative text"
416
+ return Draft(_ALT_MISSING, None, side, None, detail, element.type)
417
+ if alt and FILE_NAME_ALT.match(alt):
418
+ side = marked_side(source, alt, kind=BlockKind.IMAGE)
419
+ detail = f'the alternative text "{quote(alt)}" is a file name'
420
+ return Draft(_ALT_FILENAME, None, side, None, detail, _FILE_NAME)
421
+ return None
422
+
423
+
424
+ def _tag_drafts(doc: Document) -> list[Draft]:
425
+ """Return the drafts of the figures and tables of a structure tree.
426
+
427
+ Only the elements that were read are judged: a tree read in part gives
428
+ the drafts of its part; a missing tree gives none.
429
+ """
430
+ tags = doc.tags
431
+ if tags is None or tags.problem == NO_STRUCTURE_TREE:
432
+ return []
433
+ return [
434
+ draft
435
+ for element in tags.elements
436
+ if (draft := _tagged_draft(doc, element)) is not None
437
+ ]
438
+
439
+
440
+ def _annotation_drafts(doc: Document) -> list[Draft]:
441
+ """Return the drafts of the link annotations of a PDF that tell nothing.
442
+
443
+ The text under an annotation is judged; an empty one, as when the text
444
+ of its page was not all read, is not.
445
+ """
446
+ drafts: list[Draft] = []
447
+ for page in doc.pdf_pages:
448
+ for link in page.links:
449
+ key = _link_key(link.text)
450
+ if key not in GENERIC_LINK_TEXTS:
451
+ continue
452
+ source = SourceRef(doc.path.name, page=page.number)
453
+ side = marked_side(source, link.text)
454
+ drafts.append(_link_text_draft(side, link.text, key))
455
+ return drafts
456
+
457
+
458
+ def accessibility_drafts(
459
+ doc: Document,
460
+ thresholds: AuditThresholds,
461
+ ) -> list[Draft]:
462
+ """Return the drafts of the accessibility of a document.
463
+
464
+ Args:
465
+ doc: The audited document.
466
+ thresholds: Thresholds of the audit.
467
+
468
+ Returns:
469
+ The drafts about the whole document; then those of each HTML page,
470
+ or of each scanned PDF page; then those of the blocks, in order;
471
+ then those of the figures and tables of the structure tree of a
472
+ PDF; then those of its link annotations.
473
+ """
474
+ drafts = _document_drafts(doc, thresholds)
475
+ for page in doc.html_pages:
476
+ drafts += _html_page_drafts(page)
477
+ drafts += _scanned_drafts(doc)
478
+ drafts += _block_drafts(doc)
479
+ drafts += _tag_drafts(doc)
480
+ drafts += _annotation_drafts(doc)
481
+ return drafts
@@ -0,0 +1,136 @@
1
+ # Copyright 2026 Christophe Le Douarec
2
+ """Audit a document: run the families of checks it is asked for.
3
+
4
+ The family `STRUCTURE` checks the headings, the references, the captions and
5
+ the pages of the document, by `structure_drafts` of
6
+ `documentation_checker.audit.structure`, then its links, by
7
+ `broken_link_drafts` of `documentation_checker.audit.links`. The family `A11Y`
8
+ checks its accessibility, by `accessibility_drafts` of
9
+ `documentation_checker.audit.accessibility`, after the structure. The family
10
+ `IMAGES` checks its images, when they were read, by `image_quality_drafts` of
11
+ `documentation_checker.audit.images`, next, with a `PixelLoader` that reads
12
+ their pixels again. The family `TEXT` checks its text, by `text_drafts` of
13
+ `documentation_checker.audit.text`, last, with a `Speller` that knows the
14
+ personal words of the configuration. The drafts of the families then become
15
+ findings as those of `compare` do, by `finalize_drafts` of
16
+ `documentation_checker.compare.aggregate`: severities, filters, identifiers,
17
+ groups.
18
+ """
19
+
20
+ from dataclasses import dataclass, replace
21
+ from typing import TYPE_CHECKING, Final
22
+
23
+ from documentation_checker.audit.accessibility import accessibility_drafts
24
+ from documentation_checker.audit.images import image_quality_drafts
25
+ from documentation_checker.audit.links import broken_link_drafts
26
+ from documentation_checker.audit.structure import structure_drafts
27
+ from documentation_checker.audit.text import TEXT, text_drafts
28
+ from documentation_checker.compare.aggregate import finalize_drafts
29
+ from documentation_checker.images.load import PixelLoader
30
+ from documentation_checker.model.document import BlockKind
31
+ from documentation_checker.spell.speller import Speller
32
+
33
+ if TYPE_CHECKING:
34
+ from documentation_checker.compare.drafts import Draft
35
+ from documentation_checker.config import Config
36
+ from documentation_checker.model.document import Document
37
+ from documentation_checker.model.findings import Finding
38
+
39
+ STRUCTURE: Final = "structure"
40
+ A11Y: Final = "a11y"
41
+ IMAGES: Final = "images"
42
+
43
+
44
+ @dataclass(frozen=True, slots=True)
45
+ class AuditStats:
46
+ """Figures about an audit.
47
+
48
+ Attributes:
49
+ pages: Pages of the document: HTML pages or PDF pages.
50
+ blocks: Blocks that are not images.
51
+ images: Image blocks.
52
+ links: Links checked; ``None`` when the family `STRUCTURE`, which
53
+ checks them, did not run.
54
+ checks: Families of checks run, in the order they were asked: the
55
+ family `IMAGES` does not run when the images were not read.
56
+ profile: Profile of the audit, ``"screen"`` or ``"print"``.
57
+ images_read: Whether the images were read.
58
+ words: Words spelled; ``None`` when the family `TEXT`, which
59
+ spells them, did not run.
60
+ """
61
+
62
+ pages: int
63
+ blocks: int
64
+ images: int
65
+ links: int | None
66
+ checks: tuple[str, ...]
67
+ profile: str
68
+ images_read: bool
69
+ words: int | None = None
70
+
71
+
72
+ @dataclass(slots=True)
73
+ class AuditResult:
74
+ """Outcome of the audit of a document.
75
+
76
+ Attributes:
77
+ doc: The document, with the warnings of the family `TEXT` after
78
+ its own.
79
+ findings: The findings.
80
+ stats: Statistics.
81
+ words: The words that the dictionaries do not know, each once, as
82
+ `TextOutcome` lists them.
83
+ """
84
+
85
+ doc: Document
86
+ findings: list[Finding]
87
+ stats: AuditStats
88
+ words: tuple[str, ...] = ()
89
+
90
+
91
+ def audit_document(doc: Document, cfg: Config) -> AuditResult:
92
+ """Audit a document.
93
+
94
+ Args:
95
+ doc: The document, loaded with its audit facts.
96
+ cfg: Run configuration: its families of checks, its profile, its
97
+ thresholds, its severities and its filters.
98
+
99
+ Returns:
100
+ The findings, those of the structure first, then those of the
101
+ accessibility, of the images and of the text, each family in its
102
+ order, statistics, and the words that the dictionaries do not
103
+ know; the document is a copy that has the warnings of the text
104
+ after its own.
105
+ """
106
+ drafts: list[Draft] = []
107
+ links = None
108
+ if STRUCTURE in cfg.checks:
109
+ drafts += structure_drafts(doc)
110
+ broken, links = broken_link_drafts(doc)
111
+ drafts += broken
112
+ if A11Y in cfg.checks:
113
+ drafts += accessibility_drafts(doc, cfg.audit)
114
+ if IMAGES in cfg.checks and cfg.images:
115
+ with PixelLoader(doc.path) as loader:
116
+ drafts += image_quality_drafts(doc, loader, cfg.audit, cfg.profile)
117
+ words = None
118
+ unknown: tuple[str, ...] = ()
119
+ if TEXT in cfg.checks:
120
+ outcome = text_drafts(doc, cfg, Speller(cfg.spelling.words))
121
+ drafts += outcome.drafts
122
+ doc = replace(doc, warnings=[*doc.warnings, *outcome.warnings])
123
+ words = outcome.checked
124
+ unknown = outcome.words
125
+ images = sum(block.kind is BlockKind.IMAGE for block in doc.blocks)
126
+ stats = AuditStats(
127
+ pages=len(doc.parts),
128
+ blocks=len(doc.blocks) - images,
129
+ images=images,
130
+ links=links,
131
+ checks=tuple(c for c in cfg.checks if c != IMAGES or cfg.images),
132
+ profile=cfg.profile,
133
+ images_read=cfg.images,
134
+ words=words,
135
+ )
136
+ return AuditResult(doc, finalize_drafts(drafts, cfg), stats, unknown)