Générer la documentation

À partir de la version 10, générer la documentation est plus facile et plus rapide.

Il faut avoir installé au minimum les outils make (pour utiliser le Makefile), git (pour récupérer le dépôt de la traduction) et xsltproc (pour générer à peu près tout).

Pour générer les PDF, il faudra en plus les outils fop et java (fop étant programmé en Java).

Installation des outils nécessaires

Sur CentOS 8 par exemple :

# Outils requis
sudo dnf install -y make git libxslt
# Outils spécifiques à la génération de PDF
sudo dnf install -y java-1.8.0-openjdk
curl --output fop-2.5-bin.tar.gz https://miroir.univ-lorraine.fr/apache/xmlgraphics/fop/binaries/fop-2.5-bin.tar.gz

Le PATH doit contenir le chemin vers la commande fop, soit 👍

export PATH=~/fop-2.5/fop/fop:$PATH

Sur Fedora 31, il existe un paquet fop pour la version 2.4. C'est celui que j'utilise pour la génération de la documentation.

Récupération du dépôt git de la traduction

Cette commande suffit pour récupérer tout le dépôt :

git clone https://github.com/gleu/pgdocs_fr.git

Génération de la doc

La génération se fait en utilisant la commande make dans le répertoire pgdocs_fr.git/postgresql. Plusieurs cibles de restauration sont disponibles :

• html pour créer les fichiers HTML
• html-website pour créer les fichiers HTML avec les feuilles de style pour le site docs.postgresql.fr
• postgres-A4.pdf pour créer le fichier PDF
• maintainer-clean pour nettoyer le répertoire de tous fichiers créés pendant la génération.

Cela donnerait par exemple :

$ make html
xmllint --path . --noout --valid postgres.xml
xsltproc --path . --stringparam pg.version '13'  stylesheet.xsl postgres.xml
cp ./images/genetic-algorithm.svg ./images/pagelayout.svg ./images/gin.svg html/
cp ./css/*.css html/
touch html-stamp

Le répertoire html contient les fichiers HTML, CSS et SVG de la documentation.