Parsoid/fr



Parsoid est une bibliothèque qui permet de convertir le wikicode en HTML et réciproquement. L'application originale a été écrite en JavaScript (à l'aide de Node.js) et fut opérationnelle sur le cluster Wikimedia à partir de décembre 2012. En 2019, Parsoid a été porté en PHP et cette version PHP a remplacé la version JS sur le cluster Wikimedia en décembre 2019. Parsoid est intégré progressivement au noyau MediaWiki, dans le but de remplacer éventuellement l'analyseur natif actuel de MediaWiki.

Parsoid (dans sa version PHP) est fourni en natif avec MediaWiki depuis la version 1.35, diffusée en septembre 2020. Pour les installations non-Wikimedia installations, Parsoid / JS a été pris en charge jusqu'à la version en fin de vie de MediaWiki 1.31 (LTS) en septembre 2021.



Détails techniques
Parsoid est une application qui peut convertir de la syntaxe wikicode de MediaWiki en un modèle de document HTML / RDFa équivalent (et inversement) avec un support étendu pour le traitement automatisé et l'édition enrichie.

Il a été développé par une équipe de la Fondation Wikimedia depuis 2012. Il est actuellement utilisé de manière extensive par, , et d'autres applications.

Parsoid est destiné à fournir une conversion sans faille dans les deux sens, pour éviter la perte d'informations et également empêcher les diffs sales.

Sur les wikis Wikimedia, pour plusieurs applications, Parsoid est habituellement placé derrière, qui stocke le HTML traduit par Parsoid. Nous espérons que RESTBase soit remplacé éventuellement par un cache intégré plus fidèlement à MediaWiki.

Pour d'autres informations sur l'ensemble du projet, voir ce billet de blog de mars 2013. Pour connaitre le modèle HTML utilisé, voir les spécifications DOM de MediaWiki.

A l'origine, Parsoid a été conçu comme un service web et écrit en JavaScript, en utilisant. Une discussion technique de février 2019 (diapositives) et un billet de blog décrivent le processus de portage en PHP. L'API de l'extension Parsoid est en cours de développement; une discussion technique de août 2020 décrit ce travail.

Dépôt GitHub : https://github.com/wikimedia/parsoid

Utilisation

 * - Liste des versions de Parsoid
 * - pour l'API web
 * - pour donner un sens au HTML obtenu de l'API, conçu pour être utile à un futur format de stockage
 * - notes sur l'implémentation Parsoid de

Installation
Dans MediaWiki 1.35 LTS Parsoid / PHP est inclus dans la distribution et chargé automatiquement par l'Editeur Visuel. Pas de configuration nécessaire si utilisé avec un serveur unique.

Si vous êtes développeur et travaillez avec la version 1.36,vous devez charger explicitement Parsoid depuis le 24 août 2020 (le contournement d'auto-chargement a été supprimé en 1.36-wmf.6). Ajoutez à LocalSettings.php :

Ceci est succeptible de changer dans la version 1.36.

Développement
Les développements ont commencé dans. La revue de code a été faite dans Gerrit. Voir Débuter avec Gerrit pour configurer votre propre compte.

Si vous utilisez l'environnement de développement en utilisant une machine virtuelle, vous pouvez simplement y ajouter le role   et il définira un Parsoid opérationnel avec. (ceci peut avoir été cassé par le sélecteur Parsoid / PHP : T258940)

Notez que la version la plus récente de Parsoid qui ait été diffusée est écrite en PHP, et que l'installation de Parsoid/PHP est ce qui est décrit ci-dessous. C'est ce que vous devez utiliser si vous exécutez MediaWiki 1.35 ou plus récent. Vérifiez Parsoid/JS si vous exécutez l'ancienne version de Parsoid écrite en JavaScript et utilisée pour MW 1.34 et plus ancien.



Lier une copie développeur de Parsoid
Dans une installation MediaWiki standard, le code Parsoid est fourni de deux manières différentes : d'abord, Parsoid est inclus dans MediaWiki en tant que bibliothèque composer,. Cela comprend la base de code principale, mais ne prend pas en compte l'API REST utilisée par l'Editeur Visuel et RESTBase. Pour activer l'API REST, le code de l'extension inclus dans la bibliothèque Parsoid peut être chargé avec un appel à  dans votre.

A des fins de développement vous souhaitez souvent avoir une copie de Parsoid issu de Git, et non pas la version livrée avec le noyau MediaWiki comme bibliothèque Composer. Les lignes suivantes ajoutées à permettent l'utilisation d'une copie git de Parsoid (facultative), le chargement de l'API REST de Parsoid avec  (plutôt que d'utiliser la version embarquée dans VisualEditor) et de faire manuellement la configuration de Parsoid qui est habituellement réalisée par VisualEditor :

Ces lignes ne sont pas nécessaires pour la plupart des utilisateurs de VisualEditor, qui peuvent utiliser l'auto-configuration et le code embarqué de Parsoid inclus dans MediaWiki 1.35 et VisualEditor, mais elles seront nécessaires à la plupart des développeurs.

Si votre MediaWiki utilise les serveurs Nginx, vous devrez aussi ajouter quelque chose de similaire à ceci dans le bloc de votre serveur (en supposant que la configuration de votre MediaWiki a ses fichiers situés dans ) :

Pour tester une configuration plus propre, allez sur  où  est le nom de l'hôte (hostname) de votre fichier. (Notez que les serveurs de production de la WMF n'exposent pas l'API REST de Parsoid au réseau externe.)



Exécuter les tests
Pour exécuter tous les tests d'analyse syntaxique et les tests mocha :

Les tests de l'analyseur syntaxique possèdent maintenant quelques options que vous pouvez lister en utilisant.

Si votre variable d'environnement  pointe sur une installation de MediaWiki configurée, vous pouvez exécuter des tests supplémentaires avec :



Conversion de wikicode simple
Vous pouvez convertir de simples portions de wikicode à partir de la ligne de commande en utilisant le script  du répertoire   :

echo 'Foo' | php bin/parse.php

Le script d'analyse possède beaucoup d'options. ceci est documenté dans.



Debogage de Parsoid (pour les développeurs)
Voir pour les conseils de debogage.



Intégration continue
Depuis octobre 2021

Parsoid est toujours disponible en tant que bibliothèque car c'est une dépendance Composer du noyau MediaWiki. Mais deux éléments ne sont pas activés :


 * le ServiceWiring de Parsoid
 * l'Api REST externe de Parsoid

Le lanceur de tests Quibble va l'activer s'il détecte que  est cloné en tant que partie de la construction. Auquel cas il :


 * pointe l'autoloader de  sur le code cloné (en remplaçant effectivement la version installée par Composer)
 * charge l'extension

Le ServiceWiring doit être activé dans MediaWiki à partir de la 1.38.

L'API REST ne serait en théorie jamais fusionnée dans MediaWiki : a) elle n'a jamais été exposée au public en production, c'est une API interne utilisée par RESTBase qui va disparaître ; b) elle n'a jamais fait l'objet d'un audit de sécurité et c) elle est redondante avec l'API MediaWiki enterprise. La solution pour VisualEditor sera d'invoquer Parsoid directement via l'API Action de VisualEditor, ce qui évitera de passer par l'API REST.

Charger l'extension est ainsi une solution de contournement qui vous permet d'utiliser les interfaces sujets à modifications et que nous ne voulons pas encore réellement voir être exécutés par les utilisateurs.

Pour ces principales raisons, Parsoid ne doit pas être ajouté à la dépendance de l'intégration continue, la seule exception étant (depuis octobre 2021) l'extension Disambiguator de MediaWiki.

En chargeant Parsoid en tant qu'extension, vous pouvez exécuter les tâches des tests d'intégration de MediaWiki avec  (telles que Quibble, apitesting) et vous assurer que Parsoid et MediaWiki sont bien compatibles.

Une extension est capable d'écrire des tests avec Parsoid même quand le répertoire n'a pas été cloné. Puisqu'il s'agit d'une dépendance Composer du noyau de MediaWiki, l'espace de noms  est disponible, mais la partie câblage du service ne l'est pas (elle est   dans le dépôt de Parsoid et exposée en tant qu'espace de noms  ). Le code de  ne va lancer les tests de l'analyseur que si Parsoid a été chargé (ce qui doit être la méthode par défaut avec MediaWiki 1.38).

Pour l'intégration continue, Parsoid est testé avec l'aide de MediaWiki, alors que MediaWiki est testé avec la dépendance de Composer. En cas de modification cassant l'existant, le changement de Parsoid est d'abord fusionné (ce qui casse son intégration continue mais pas celle de MediaWiki) et MediaWiki est ajusté lorsque Parsoid est mis à jour. Ainsi la modification est à sens unique.



Construction des versions
Pour les versions des constructions MediaWiki, nous avons une intégration du ServiceWiring de Parsoid dans l'ÉditeurVisuel afin que ce dernier fonctionne sans configuration supplémentaire (à part un ). La construction de la version permet aussi d'utiliser l'API REST et toutes les accroches, ce qui permet à Parsoid de s'exécuter immédiatement. Ceci est réalisé en copiant une partie du code Parsoid dans VisualEditor mais pas dans la branche master de VisualEditor car cela serait obsolète aussitôt que Parsoid serait remis à jour. En remplacement, le code est maintenu à deux endroits.



Documents techniques

 * Parsoid/Internals: documentation à propos des éléments internes de Parsoid avec des liens vers d'autres détails.
 * notes du portage en PHP et tâches d'aide demandée
 * agenda de déploiement Parsoid sur les clusters Wikimedia (code normalement déployé chaque lundi et mercredi entre 1 heure pm et 1 heure 30 pm PST)
 * Parsoid/Round-trip testing: configuration de test aller-retour utilisée pour tester l'aller-retour wikicode -> HTML DOM -> wikicode sur le contenu actuel de Wikipedia.
 * Parsoid/Visual Diffs Testing: Informations à propos du test visuel des diff pour comparer le rendu html de Parsoid avec le générateur de rendu html de l'analyseur PHP et une configuration réduite de test pour les tests visuels de diff en masse.
 * Parsoid/limitations: Limitations de Parsoid, principalement des utilisations et cas artificiels de modèles qui n'ont pas d'importance dans la pratique. Peut être étendu pour être similaire aux notes de mise à jour du pré-processeur (à mettre à jour éventuellement)
 * Parsoid/Bibliography: Bibliographie de littérature relative



Liens pour les développeurs Parsoid

 * Voir Parsoid/Debugging pour les conseils de debogage.
 * Mettre à jour ou ajouter des paquets à Parsoid
 * Voir ces instructions pour synchroniser la copie Parsoid des tests de l'analyseur syntaxique vers, ou à partir du noyau
 * Parsoid possède une interface de bibliothèque limitée pour l'invoquer dans un programme.
 * Discussion technique au sujet du reciblage des extensions pour fonctionner avec Parsoid
 * Donc si vous voulez que votre extension fonctionne avec Parsoid
 * Spécifications de version du HTML de Parsoid
 * Donc vous allez changer la sortie de Parsoid



Liens pour le déploiement de Parsoid (sur les grappes Wikimedia)

 * Parsoid/Deployments
 * test des validations en temps réel (utile pour vérifier la non régression et les corrections)
 * Instructions de déploiement de Parsoid
 * Tableau de bord Kibana
 * Tableau de bord Grafana pour les métriques wt2html (du wikicode vers HTML)
 * Tableau de bord Grafana pour les métriques html2wt (du HTML vers wikicode)
 * Tableau de bord Grafana pour les réponses 'non-200'
 * Distribution de Prometheus pour le cluster Parsoid sur data center Eqiad
 * Distribution de Prometheus pour le cluster Parsoid sur data center Codfw
 * Documents du Job Builder de Jenkins pour la mise à jour des tâches jenkins



Voir aussi

 * API
 * RESTBase: proxy d'API pour la mise en cache et l'enregistrement du HTML traduit par Parsoid
 * Réunions de revue trimestrielles de l'équipe Parsoid : avril 2015, janvier 2015 (précédents)
 * Future/Parser plan: Idées initiales (maintenant relativement anciennes) d'architecture et problèmes
 * Special:PrefixIndex/Parsoid/: Pages sur ce wiki relatives à Parsoid
 * Extension:ParsoidBatchAPI (archivé)
 * parsoid-jsapi : interface de haut niveau pour l'extraction et la transformation du wikicode, similaire à l'API mwparserfromhell.
 * Analyseurs alternatifs
 * Parsoid/Parser Unification



Liens externes

 * Code source (miroir GitHub)
 * Documentation JavaScript (ancienne version de Parsoid)
 * Documentation PHP
 * Parsoid sur Wikimedia Commons

Contact
Si vous avez besoin d'aide ou si vous avez des question ou des commentaires, vous pouvez nous contacter sur ou par la liste de diffusion wikitext-l. Si vous n'y arrivez pas, contactez-nous par courriel à parsing-team sur le domaine wikimedia.org.