Parsoid

Suivi des problèmes : #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 100% complete.
Languages:
Projets de la Fondation Wikimedia
Parsoid
Bibliothèque d'analyse bidirectionnelle de wiki code. Permet de passer du wikicode au DOM HTML/XML avec RDFa, et réciproquement.
Groupe : Content Transform Team
Début : 2011-10
Membres de l'équipe : Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Shannon Bailey, Yiannis Giannelos
Direction : Subramanya Sastry
Gestion : Sérgio Lopes
Parsoid HTML5 + RDFa et ses interfaces dans le wiki

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. In early 2024, Parsoid began to be used on some production wikis as the default parser for read views.

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. The legacy parser will still be supported in MediaWiki 1.43 (LTS).

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 VisualEditor , Structured discussions , Traduction de contenu 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 RESTBase , 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 Node.js. 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

Installation

Dans MediaWiki 1.35 Parsoid / PHP est inclus dans la distribution et chargé automatiquement par l'Editeur Visuel. Pas de configuration nécessaire avec Mediawiki 1.35+ .

Parsoid exports an internal REST API which was historically used by RESTBase and not accessible outside the WMF internal cluster. This is no longer required for Visual Editor or core read views, and the internal API is being deprecated and is planned for removal in MW 1.43.

Parsoid is nominally a composer library used by mediawiki core. If you still require the internal API for some reason, you can explicitly load Parsoid "as an extension" by adding the following to LocalSettings.php: 

wfLoadExtension( 'Parsoid', "$IP/vendor/wikimedia/parsoid/extension.json" );

Any remaining third-party users of the internal Parsoid API are strongly encouraged to migrate to the core REST HTML page endpoint which provides equivalent functionality.

Développement

Les développements ont commencé dans Parsoid Git repository. 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 MediaWiki-Vagrant en utilisant une machine virtuelle, vous pouvez simplement y ajouter le role visualeditor et il définira un Parsoid opérationnel avec Extension:VisualEditor . (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, Parsoid est inclus dans MediaWiki en tant que bibliothèque composer, wikimedia/parsoid.

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 à LocalSettings.php permettent l'utilisation d'une copie git de Parsoid (facultative), le chargement de l'API REST de Parsoid avec wfLoadExtension (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 : 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # copie embarquée
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// Pour les développeurs : assurez-vous que Parsoid est exécuté à partir de $parsoidInstallDir,
// (pas la version incluse par défaut dans le noyau MediaWiki)
// doit s'exécuter *avant* wfLoadExtension()
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // Only intercept Parsoid namespace classes
        if ( preg_match( '/(MW|Wikimedia\\\\)Parsoid\\\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // AutoLoader::registerNamespaces a été ajouté dans MW 1.39
    AutoLoader::registerNamespaces( [
        // garder cela synchronisé avec la clause "autoload" dans
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src",
    ] );
}

wfLoadExtension( 'Parsoid', "$parsoidInstallDir/extension.json" );

# Configurer manuellement Parsoid
$wgVisualEditorParsoidAutoConfig = false;
$wgParsoidSettings = [
    'useSelser' => true,
    'rtTestMode' => false,
    'linting' => false,
];
$wgVirtualRestConfig['modules']['parsoid'] = [
    // URL de l'instance Parsoid.
    // Si Parsoid ne s'exécute pas localement, modifier $wgServer pour qu'il corresponde à l'hôte non local 
    // Si Docker est utilisé sous macOS, remplacez éventuellement $wgServer par http://host.docker.internal:8080
    // Si Docker est utilisé sous linux, remplacez éventuellement $wgServer par http://172.17.0.1:8080
    'url' => $wgServer . $wgScriptPath . '/rest.php',
    // ''domaine'' Parsoid, voir ci-dessous (facultatif, rarement nécessaire)
    // 'domain' => 'localhost',
];
unset( $parsoidInstallDir );

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 /w/) : 

location /w/rest.php/ {
    try_files $uri $uri/ /w/rest.php?$query_string;
}

Pour tester une configuration plus propre, allez sur {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page où $domain est le nom de l'hôte (hostname) de votre fichier $wgCanonicalServer. (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 : 

$ composer test

Les tests de l'analyseur syntaxique possèdent maintenant quelques options que vous pouvez lister en utilisant php bin/parserTests.php --help.

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

$ composer phan-integrated

Conversion de wikicode simple

Vous pouvez convertir de simples portions de wikicode à partir de la ligne de commande en utilisant le script parse.php du répertoire bin/ : 

echo 'Foo' | php bin/parse.php

Le script d'analyse possède beaucoup d'options. ceci est documenté dans php bin/parse.php --help.

Debogage de Parsoid (pour les développeurs)

Voir Parsoid/Debugging 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 mediawiki/services/parsoid.git est cloné en tant que partie de la construction. Auquel cas il :

  • pointe l'autoloader de Wikimedia\Parsoid sur le code cloné (en remplaçant effectivement la version installée par Composer)
  • charge l'extension wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

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 mediawiki/services/parsoid.git (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 MediaWiki\Parsoid est disponible, mais la partie câblage du service ne l'est pas (elle est extension/src dans le dépôt de Parsoid et exposée en tant qu'espace de noms \MWParsoid). Le code de ParsoidTestFileSuite.php 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 wfLoadExtension( 'VisualEditor' )). 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

Liens pour les développeurs Parsoid

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

Voir aussi

Liens externes

Contact

Si vous avez besoin d'aide ou si vous avez des question ou des commentaires, vous pouvez nous contacter sur #mediawiki-parsoid connecter 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.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Parsoid/fr&oldid=6435294"