Parsoid/fr



Parsoid est une bibliothèque qui permet de convertir le wikitext 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 dans la syntaxe du 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 blogdécrivent le processus du 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é en. La revue de code a été faite dans Gerrit. Voir Débuter dans 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 :


 * points the autoloader for  to the cloned code (effectively replacing the version installed by composer)
 * charge l'extension

ServiceWiring doit être activé dans MediaWiki en commençant avec la 1.38.

The REST API would theorically never get merged in MediaWiki: a) it has never been exposed to the public in production, it is an internal API used by RESTBase which is going away; b) it never has been security audited and c) it is redundant with the enterprise MediaWiki API. 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é. Since it is a composer dependency of MediaWiki core the  namespace is available, but the service wiring part is not (it is   in the Parsoid repository and exposed as the   namespace). 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. In case of a breaking change, the Parsoid change get merged first (which breaks its CI but not MediaWiki one) and MediaWiki get adjusted when Parsoid is updated. Ainsi la modification est à sens unique.



Construction des versions
For MediaWiki release builds, we have an integration of Parsoid ServiceWiring into VisualEditor in order to have VisualEditor work without further configuration (beside a ). 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 about Parsoid internals with links to other details.
 * PHP Porting notes and help-wanted tasks
 * Parsoid deployment agenda on Wikimedia cluster (code normally deployed every Monday and Wednesday between 1pm - 1:30pm PST)
 * Parsoid/Round-trip testing: The round-trip testing setup we are using to test the wikitext -> HTML DOM -> wikitext round-trip on actual Wikipedia content.
 * Parsoid/Visual Diffs Testing: Info about visual diff testing for comparing Parsoid's html rendering with php parser's html rendering + a testreduce setup for doing mass visual diff tests.
 * Parsoid/limitations: Limitations in Parsoid, mainly contrived templating (ab)uses that don't matter in practice. Could be extended to be similar to the preprocessor upgrade notes (Might need updating)
 * Parsoid/Bibliography: Bibliography of related literature



Liens pour les développeurs Parsoid

 * See Parsoid/Debugging for debugging tips.
 * Upgrading or adding packages to Parsoid
 * See these instructions for syncing Parsoid's copy of parser tests to/from core
 * Parsoid has a limited library interface for invoking it programatically.
 * Tech Talk about Retargeting extensions to work with Parsoid
 * So you want your extension to work with Parsoid
 * Parsoid HTML Specification Versioning
 * So you are going to change Parsoid output



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

 * Parsoid/Deployments
 * RT testing commits (useful to check regressions and fixes)
 * Deployment instructions for Parsoid
 * Kibana dashboard
 * Grafana dashboard for wt2html metrics
 * Grafana dashboard for html2wt metrics
 * Grafana dashboard for non-200 responses
 * Prometheus breakdown for the Parsoid cluster on eqiad
 * Prometheus breakdown for the Parsoid cluster on codfw
 * Jenkins Job Builder docs for updating jenkins jobs



Voir aussi

 * API
 * RESTBase: a caching / storing API proxy for page HTML translated by Parsoid
 * Quarterly review meetings of the Parsoid team: April 2015, January 2015 (earlier)
 * Future/Parser plan: Early (now relatively old) design ideas and issues
 * Special:PrefixIndex/Parsoid/: Parsoid-related pages on this wiki
 * Extension:ParsoidBatchAPI (archived)
 * parsoid-jsapi: a high-level interface for extraction and transformation of wikitext, similar to the mwparserfromhell API.
 * Alternative parsers
 * Parsoid/Parser Unification



Liens externes

 * Source code (GitHub mirror)
 * JS Documentation (old version of Parsoid)
 * PHP Documentation
 * Parsoid on the Wikimedia Commons

Contact
If you need help or have questions/feedback, you can contact us in or the wikitext-l mailing list. If all that fails, you can also contact us by email at parsing-team at the wikimedia.org domain.