docs: add one-command README HTML/PDF export

2026-07-23 05:48:43 +04:00
parent 3d28d3832f
commit 5b1a78782a
4 changed files with 171 additions and 2 deletions
@@ -25,6 +25,10 @@ temp/
 # Fichiers de cache
 cache/

+# Artefacts de documentation générés (docs/generate-readme-pdf.sh)
+README.html
+README.pdf
+
 # Dossier pour les images d'annonces (tout ignorer sauf .gitkeep)
 uploads/*
 !uploads/.gitkeep
@@ -161,7 +161,9 @@ Toutes ces sources sont modifiables dans `includes/config.local.php` (voir <<fr-
 │   ├── castopod-podcasts.css       #   castopod, funkwhale, wordpress, grille…)
 │   └── …
 ├── docs/
-│   └── wireframes/                 # Maquettes d'origine (PNG desktop + mobile)
+│   ├── wireframes/                 # Maquettes d'origine (PNG desktop + mobile)
+│   ├── docinfo.html                # Styles d'impression (fallback emoji) pour l'export
+│   └── generate-readme-pdf.sh      # Export de la doc : README.html / README.pdf
 ├── img/                            # Logo, favicons, icône de lecture
 ├── includes/
 │   ├── config.php                  # Bootstrap + fonctions API (PeerTube, Castopod,
@@ -870,6 +872,23 @@ Bonnes pratiques du dépôt :
 - Ne versionnez jamais `config.local.php` ni les fichiers dérivés des `.sample`
 - Quelques constantes sont définies mais non utilisées par le code actuel (`ENABLE_SEARCH`, `ENABLE_COMMENTS`, `ENABLE_USER_ACCOUNTS`, `TAG_SHORT`) : ne vous en servez pas comme points d'extension

+==== 📄 Exporter la documentation (HTML / PDF)
+
+Ce README peut être exporté en HTML et en PDF en une seule commande :
+
+[source,bash]
+----
+docs/generate-readme-pdf.sh           # README.html + README.pdf
+docs/generate-readme-pdf.sh --html    # HTML seulement
+docs/generate-readme-pdf.sh --pdf     # PDF seulement
+----
+
+Les fichiers sont produits à la racine du projet et ignorés par Git (`.gitignore`).
+
+Prérequis : `asciidoctor`, `chromium` (rendu headless) et le paquet `fonts-noto-color-emoji` (émojis couleur dans le PDF). La feuille de style `docs/docinfo.html` (fallback emoji + règles d'impression) est injectée automatiquement via le mécanisme `docinfo` d'Asciidoctor.
+
+NOTE: `asciidoctor-pdf` (utilisé par l'extension AsciiDoc de VSCodium) n'est pas utilisable ici : son moteur Prawn ne sait pas embarquer les polices emoji couleur (CBDT/COLR), les émojis disparaissent du PDF. Chromium les gère nativement.
+
 === 📜 Licence

 Copyright (C) 2025 Cédric Famibelle-Pronzola & *ORGANISATION KA INTERNATIONALE*
@@ -1034,7 +1053,9 @@ All of these sources can be changed in `includes/config.local.php` (see <<en-con
 │   ├── castopod-podcasts.css       #   castopod, funkwhale, wordpress, grid…)
 │   └── …
 ├── docs/
-│   └── wireframes/                 # Original mockups (desktop + mobile PNGs)
+│   ├── wireframes/                 # Original mockups (desktop + mobile PNGs)
+│   ├── docinfo.html                # Print styles (emoji fallback) for the export
+│   └── generate-readme-pdf.sh      # Docs export: README.html / README.pdf
 ├── img/                            # Logo, favicons, play icon
 ├── includes/
 │   ├── config.php                  # Bootstrap + API functions (PeerTube, Castopod,
@@ -1743,6 +1764,23 @@ Repository best practices:
 - Never version `config.local.php` or files derived from the `.sample` files
 - A few constants are defined but unused by the current code (`ENABLE_SEARCH`, `ENABLE_COMMENTS`, `ENABLE_USER_ACCOUNTS`, `TAG_SHORT`): do not rely on them as extension points

+==== 📄 Exporting the documentation (HTML / PDF)
+
+This README can be exported to HTML and PDF with a single command:
+
+[source,bash]
+----
+docs/generate-readme-pdf.sh           # README.html + README.pdf
+docs/generate-readme-pdf.sh --html    # HTML only
+docs/generate-readme-pdf.sh --pdf     # PDF only
+----
+
+Files are produced in the project root and are Git-ignored (`.gitignore`).
+
+Requirements: `asciidoctor`, `chromium` (headless rendering) and the `fonts-noto-color-emoji` package (color emoji in the PDF). The `docs/docinfo.html` stylesheet (emoji fallback + print rules) is automatically injected through Asciidoctor's `docinfo` mechanism.
+
+NOTE: `asciidoctor-pdf` (used by VSCodium's AsciiDoc extension) cannot be used here: its Prawn engine cannot embed color-emoji fonts (CBDT/COLR), so emoji disappear from the PDF. Chromium handles them natively.
+
 === 📜 License

 Copyright (C) 2025 Cédric Famibelle-Pronzola & *ORGANISATION KA INTERNATIONALE*
@@ -0,0 +1,58 @@
+<!-- Injected by Asciidoctor when generating the print/PDF HTML variant.
+     Usage: asciidoctor -a docinfodir=docs -a docinfo=shared README.adoc -o README-print.html
+     Fixes color-emoji rendering in headless Chromium and adapts the layout for print. -->
+<style>
+/* Font stacks with an explicit emoji fallback. "Noto Color Emoji" must be
+   installed system-wide (package: fonts-noto-color-emoji). */
+* {
+    font-family: "Noto Sans", "Noto Color Emoji", sans-serif !important;
+}
+pre, code, kbd, samp {
+    font-family: "Noto Sans Mono", "Noto Color Emoji", monospace !important;
+}
+
+@media print {
+    /* The left-floating TOC is screen-only; bring it back into the flow */
+    #header, #toc {
+        position: static !important;
+        width: auto !important;
+        max-width: none !important;
+        float: none !important;
+        height: auto !important;
+        overflow: visible !important;
+    }
+    #content {
+        margin: 0 !important;
+        padding: 0 !important;
+        max-width: none !important;
+    }
+    body {
+        margin: 0;
+        font-size: 10pt;
+        line-height: 1.35;
+    }
+    /* Keep headings with their content, break tables between rows only */
+    h1, h2, h3, h4, h5, h6 {
+        page-break-after: avoid;
+    }
+    tr, td, th, .admonitionblock, .imageblock {
+        page-break-inside: avoid;
+    }
+    /* Long code listings may overflow the page width: allow wrapping */
+    pre {
+        white-space: pre-wrap;
+        word-wrap: break-word;
+    }
+    img {
+        max-width: 100%;
+    }
+    /* Links are not clickable in a PDF: keep them readable, not blue */
+    a {
+        color: inherit;
+        text-decoration: none;
+    }
+    a[href^="http"]::after {
+        content: "";
+    }
+}
+</style>
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Generate the documentation export(s) from README.adoc.
+#
+#   docs/generate-readme-pdf.sh           # README.html + README.pdf
+#   docs/generate-readme-pdf.sh --html    # README.html only
+#   docs/generate-readme-pdf.sh --pdf     # README.pdf only
+#
+# Both outputs land in the project root and are Git-ignored.
+#
+# Requirements:
+#   - asciidoctor            (e.g. gem install asciidoctor)
+#   - chromium               (headless PDF rendering)
+#   - fonts-noto-color-emoji (color emoji in the PDF)
+#
+# Why Chromium instead of asciidoctor-pdf (used by the VSCodium extension)?
+# Its Prawn engine cannot embed color-emoji fonts (CBDT/COLR), so emoji
+# disappear. Chromium handles them fine as long as "Noto Color Emoji"
+# is installed. The docs/docinfo.html stylesheet (emoji fallback + print
+# rules) is injected only for this build, via Asciidoctor's docinfo
+# mechanism, and adapts the layout for print (TOC in flow, table/page
+# breaks, wrapped code listings).
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+MODE="${1:---all}"
+HTML_OUT="README.html"
+PDF_OUT="README.pdf"
+
+build_html() {
+    asciidoctor -b html5 -a docinfodir=docs -a docinfo=shared README.adoc -o "$1"
+    echo "HTML generated: $1"
+}
+
+build_pdf() {
+    # Resolve to an absolute path for the file:// URL
+    local html_path="$1"
+    [[ "$html_path" != /* ]] && html_path="$PWD/$html_path"
+    chromium --headless --disable-gpu --no-sandbox \
+        --no-pdf-header-footer \
+        --print-to-pdf="$PDF_OUT" \
+        "file://$html_path"
+    echo "PDF generated: $PDF_OUT"
+}
+
+case "$MODE" in
+    --html)
+        build_html "$HTML_OUT"
+        ;;
+    --pdf)
+        TMP_HTML="$(mktemp --suffix=.html)"
+        trap 'rm -f "$TMP_HTML"' EXIT
+        build_html "$TMP_HTML" >/dev/null
+        build_pdf "$TMP_HTML"
+        ;;
+    --all)
+        build_html "$HTML_OUT"
+        build_pdf "$HTML_OUT"
+        ;;
+    -h|--help)
+        sed -n '2,10p' "$0"
+        exit 0
+        ;;
+    *)
+        echo "Usage: $0 [--html|--pdf|--all]" >&2
+        exit 1
+        ;;
+esac