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 is intended to provide flawless back-and-forth conversion, i.e. to avoid information loss and also prevent "dirty diffs".

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. A tech talk from February 2019 (slides) and blog post describes the process of porting it to 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.

If you use the development environment using a virtual machine, you can simply add the role   to it and it will set up a working Parsoid along with. (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.

For development purposes you usually want to use a git checkout of Parsoid, and not the version bundled in MediaWiki core as a composer library. The following lines added to allow use of a git checkout of Parsoid (optionally), load the Parsoid REST API with  (rather than using the version bundled in VisualEditor) and manually do the Parsoid configuration which is usually done by VisualEditor:

These lines are not necessary for most users of VisualEditor, who can use auto-configuration and the bundled Parsoid code included in MediaWiki 1.35 and VisualEditor, but they will be required for most developers.

If you're serving MediaWiki with Nginx, you'll need to also add something like this in your server block (Assuming your MediaWiki setup has its files residing in ):

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)
 * Charger 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.

For most purposes, parsoid should thus not be added as a CI dependency, the only exception as of October 2021 is the Disambiguator MediaWiki extension.

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.