mirror of
https://github.com/nlohmann/json.git
synced 2026-10-03 21:20:30 +00:00
Niels Lohmann
63c10a51fc
* Review and extend the documentation, and check it in CI A review of all documentation pages found factual errors, dead links, missing cross-references, and gaps in examples. This fixes them and adds checks so the same problems are caught automatically. Fixes: - wrong signatures and version histories (operator!= C++20 member, binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...) - stale descriptions (number parsing since #5283, UBJSON table, SAX example that no longer compiled, tsl::ordered_map advice) - dead internal and external links; repology.org badges (the domain is suspended) replaced by badges that query the registries directly - deprecation notes link the migration guide; the guide itself fixed Additions: - "See also" sections, cross-references, 25 runnable examples, 12 Mermaid diagrams, new API pages for json_pointer::operator<=> and byte_container_with_subtype::operator==/!= - landing page, guides for untrusted input and performance - "unreleased" badge after versions newer than the latest release Checks: - strict documentation build (broken links/anchors fail it); CI and the publish workflow fetch the full history the build needs - weekly external link check, Mermaid syntax check in CI - check_structure.py: example titles, heading levels, alt texts, header links, docset index coverage; its unused-example check works again - all examples produce the same output on every platform Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Keep the customer links that could not be fixed A dead link on the customers page is still the evidence of where the use of the library was documented. Keep the original URLs of the entries without a working replacement (Marne, Cisco Webex Desk Camera, Philips Hue, CyberArk) and exclude exactly these URLs from the link check. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct the duplicate-key recipe's claim about SAX positions The SAX interface's key() receives no position either; only parse_error() does. Also note that the recipe does not report the path to the repeated key (see discussion #5085). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Say the library is available as a single header and mention json_fwd.hpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct documentation errors found while hunting for bugs - patch/patch_inplace: list the JSON pointer errors parse_error.106-109 and out_of_range.402/404, and quote the actual parse_error.105 message. - unflatten: list parse_error.106/107/108 and out_of_range.404. - to_bson: list out_of_range.415 (binary subtype above 255) and note that 412 and 415 are new in 3.13.0. - to_string: state that string_t must be convertible to std::string, also in the StringType requirements table. - JSON Lines: a `while (input >> j)` loop also throws after the last value for concatenated JSON values; show a loop that works for both. - BON8: a string gets 0xFF only if nothing follows it in the message; a string at the end of an array or object is ended by 0xFE. - custom_string_type.hpp: add operator+=(char), which the "Always required" list asks for (json_pointer::to_string, flatten, unflatten, and diff did not compile), and an ADL int_to_string for diff and items. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Cache the release headers with functools.lru_cache Codacy (Pylint) flagged the mutable default argument that header() used as its cache. functools.lru_cache keeps the same memoization without it. The script's output is unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
55 lines
2.3 KiB
JavaScript
55 lines
2.3 KiB
JavaScript
// Check that every Mermaid diagram in the documentation parses.
|
|
//
|
|
// MkDocs does not validate Mermaid diagrams; a syntax error only shows up as an error box in the browser. This script
|
|
// extracts every ```mermaid block from the Markdown files and runs it through mermaid.parse(), the same parser the
|
|
// site uses (Material for MkDocs loads mermaid@11). Mermaid needs a DOM (DOMPurify), so jsdom provides one; the globals
|
|
// must be set before Mermaid is imported, hence the dynamic import.
|
|
//
|
|
// usage: node check_mermaid.mjs <docs directory>
|
|
|
|
import { readdirSync, readFileSync } from 'node:fs';
|
|
import { join } from 'node:path';
|
|
import { JSDOM } from 'jsdom';
|
|
|
|
const { window } = new JSDOM('<!DOCTYPE html><html><body></body></html>', { pretendToBeVisual: true });
|
|
globalThis.window = window;
|
|
globalThis.document = window.document;
|
|
globalThis.DOMParser = window.DOMParser;
|
|
const { default: mermaid } = await import('mermaid');
|
|
mermaid.initialize({ startOnLoad: false });
|
|
|
|
const docsDir = process.argv[2] ?? 'docs';
|
|
const opening = /^(\s*)(`{3,}|~{3,})\s*mermaid\s*$/;
|
|
let diagrams = 0;
|
|
let errors = 0;
|
|
|
|
for (const file of readdirSync(docsDir, { recursive: true }).filter((f) => f.endsWith('.md')).sort()) {
|
|
const lines = readFileSync(join(docsDir, file), 'utf8').split('\n');
|
|
for (let i = 0; i < lines.length; ++i) {
|
|
const match = opening.exec(lines[i]);
|
|
if (!match) {
|
|
continue;
|
|
}
|
|
// strip the indentation of the opening fence from every line (blocks inside admonitions or lists), like
|
|
// pymdownx.superfences does
|
|
const [, indent, fence] = match;
|
|
const closing = new RegExp(`^\\s*\\${fence[0]}{${fence.length},}\\s*$`);
|
|
const body = [];
|
|
let j = i + 1;
|
|
for (; j < lines.length && !closing.test(lines[j]); ++j) {
|
|
body.push(lines[j].startsWith(indent) ? lines[j].slice(indent.length) : lines[j].trimStart());
|
|
}
|
|
++diagrams;
|
|
try {
|
|
await mermaid.parse(body.join('\n'));
|
|
} catch (error) {
|
|
++errors;
|
|
console.log(`${join(docsDir, file)}:${i + 1}: ${String(error?.message ?? error).replaceAll('\n', '\n ')}`);
|
|
}
|
|
i = j;
|
|
}
|
|
}
|
|
|
|
console.log(`checked ${diagrams} Mermaid diagrams, ${errors} invalid`);
|
|
process.exitCode = errors ? 1 : 0;
|