Jump to content

Parsoid

Hibakövető: #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 59% complete.
Outdated translations are marked like this.
Languages:
A Wikimédia Alapítvány projektjei
Parsoid
Kétirányú, futásidejű wikiszöveg-parser. Kétirányú átalakítást végez a wikiszöveg és az RDFa-t tartalmazó HTML/XML DOM között.
Csoport: Content Transform Team
Kezdés: 2011-10
Csapattagok: Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Otto Šleger, Subramanya Sastry, Yiannis Giannelos
Elintézetlen ügyek: #parsoid
Vezető: C.Scott Ananian
Vezetőség: Sérgio Lopes
Újdonságok: Parsoid/Releases
Folyamat: Parsoid/Deployments
A Parsoid HTML5 + RDFa wikifuttatási környezetének diagramja
A Parsoid 2020-ig JavaScriptben (Node.js-ben) írt korábbi változatát lásd itt: Parsoid/JS .

A Parsoid egy PHP-könyvtár, amely a wikiszöveg és a HTML közötti kétirányú átalakításra szolgál. 2012 óta fejlesztik; eredetileg JavaScriptben írták, és a VisualEditor támogatására hozták létre. A MediaWiki 1.35-ös verziója óta annak része. A tervek szerint a MediaWiki 1.47-ben a Parsoid válik a MediaWiki alapértelmezett parserévé, felváltva a jelenlegi natív parsert , a parseregységesítés nevű projekt keretében.

Technikai részletek

A Parsoid egy olyan alkalmazás, amely kétirányú átalakítást végez a MediaWiki wikiszöveg-szintaxisa és az annak megfelelő HTML/RDFa dokumentummodell között, továbbfejlesztett támogatást nyújtva az automatizált feldolgozáshoz és a vizuális szerkesztéshez.

A Wikimedia Alapítvány egyik csapata 2012 óta fejleszti. Jelenleg széles körben használja a VisualEditor , a Tartalomfordító és más alkalmazások.

A Parsoid célja a hibátlan kétirányú átalakítás biztosítása, vagyis az információvesztés elkerülése és a „piszkos eltérések” megelőzése.

A Wikimédia-wikiken több alkalmazás esetében a Parsoid jelenleg a RESTBase mögött, proxyn keresztül érhető el; a RESTBase tárolja a Parsoid által előállított HTML-t. A RESTBase-t várhatóan idővel felváltja egy, a MediaWikivel szorosabban integrált gyorsítótár.

A teljes projektről további információkat a 2013. márciusi blogbejegyzésben találsz. A használt HTML-modellről a MediaWiki DOM-specifikációban olvashatsz.

A Parsoidot eredetileg webszolgáltatásként alakították ki, JavaScriptben írták, és a Node.js-et használta. Egy 2019. februári technikai előadás (diák) és egy blogbejegyzés ismerteti a PHP-ra való átültetés folyamatát. A Parsoid kiterjesztés API-ja jelenleg aktív fejlesztés alatt áll; ezt a munkát egy 2020. augusztusi technikai előadás ismerteti.

GitHub-tárhely: https://github.com/wikimedia/parsoid

Használat

Telepítés

Ezt a kiterjesztést a MediaWiki 1.35 és afölötti verziói már tartalmazzák, így nem kell újra letöltened. The remaining configuration instructions must still be followed.

A Parsoid a MediaWiki része az 1.35 verziótól. Bekapcsolása nem igényel konfigurálást.

A Parsoid egy belső REST API-t biztosít, amelyet korábban a RESTBase használt, és amely a Wikimedia Alapítvány belső fürtjén kívülről nem volt elérhető. Erre a VisualEditornek és a MediaWiki magjának olvasási nézeteihez már nincs szükség; a belső API elavulttá van nyilvánítva, és a tervek szerint a MediaWiki 1.43-ban eltávolítják.

A Parsoid névlegesen egy Composer-könyvtár, amelyet a MediaWiki magja használ. Ha valamilyen okból továbbra is szükséged van a belső API-ra, a következő sor LocalSettings.php-hez való hozzáadásával kifejezetten betöltheted a Parsoidot „kiterjesztésként”: 

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

A belső Parsoid API-t még használó külső felhasználóknak erősen ajánlott áttérniük a MediaWiki magjának REST-alapú HTML-lapvégpontjára, amely egyenértékű funkcionalitást biztosít.

Fejlesztés

A fejlesztés a Parsoid Git repositoryban történik. A kódelemzés a Gerritben történik. A fióklétrehozáshoz lásd: Gerrit/Getting started.

Ha a MediaWiki-Vagrant fejlesztői környezetet virtuális gépen használod, egyszerűen add hozzá a visualeditor szerepkört, amely beállít egy működő Parsoidot a Extension:VisualEditor ral együtt.

Az alábbi utasítások a MediaWiki 1.35-ös vagy újabb verzióira vonatkoznak. Ha a Parsoid régi, JavaScriptben írt, a MediaWiki 1.34-es és korábbi verzióihoz használt változatát futtatod, lásd: Parsoid/JS .

A Parsoid fejlesztői példányának csatolása

Egy szabványos MediaWiki-telepítésben a Parsoid Composer-könyvtárként, wikimedia/parsoid néven része a MediaWikinek.

Fejlesztési célokra általában a Parsoid Gitből lekért munkapéldányát célszerű használni, nem pedig a MediaWiki magjába Composer-könyvtárként beépített változatot. A következő sorok LocalSettings.php -hez való hozzáadásával használható a Parsoid Gitből lekért munkapéldánya (opcionálisan), betölthető a Parsoid REST API-ja a wfLoadExtension használatával (a VisualEditorbe beépített változat helyett), valamint kézzel elvégezhető a Parsoid azon konfigurációja, amelyet általában a VisualEditor hajt végre: 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # beépített példány
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// Fejlesztőknek: győződj meg arról, hogy a Parsoid a $parsoidInstallDir helyről fut,
// (nem pedig a mediawiki-core-ban alapértelmezés szerint megtalálható változat)
// A wfLoadExtension() előtt kell szerepelnie
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // Csak a Parsoid névteréhez tartozó osztályokat irányítsa át
        if ( preg_match( '/(MW|Wikimedia\\\\)Parsoid\\\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // az MW 1.39-ben jelent meg az AutoLoader::registerNamespaces
    AutoLoader::registerNamespaces( [
        // tartsd szinkronban az „autoload” záradékkal itt:
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src/",
    ] );
}

wfLoadExtension( 'Parsoid', "$parsoidInstallDir/extension.json" );
unset( $parsoidInstallDir );
Unit tests in mediawiki-core do not use the standard autoloader (or LocalSettings.php) and so will not pick up your local Parsoid; set MEDIAWIKI_HAS_INTEGRATION_TESTS=1 in your environment to force the use of LocalSettings.php and the autoloader when running core unit tests against your local Parsoid checkout.

Ezekre a sorokra a VisualEditor legtöbb felhasználójának nincs szüksége, mivel használhatják a VisualEditor automatikus konfigurációját és a MediaWikihez mellékelt Parsoid-kódot, a legtöbb fejlesztő számára azonban szükségesek.

Ha a MediaWikit Nginx segítségével szolgálod ki, a kiszolgálóblokkjához valami ehhez hasonlót is hozzá kell adnod (feltételezve, hogy a MediaWiki telepítési fájljai a /w/ helyen találhatók): 

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

Ha a MediaWikit Dockerben futtatod, és a helyi Parsoid-tárolódat hozzákapcsolod a MediaWikihez, a MediaWiki-projekt docker-compose.override.yml fájljában egy további kötetet kell hozzárendelned a Docker-konténerhez. Ehhez a legegyszerűbb, ha létrehozod a docker-compose.override.yml fájlt a MediaWiki-projektben, és beilleszted az alábbi kódot (az elérési út megfelelő módosításával). Ha már van docker-compose.override.yml fájlod, módosítsd ennek megfelelően. 

services:
  mediawiki:
    volumes:
      - ./:/var/www/html/w:cached
      - /my/path/to/git/checkout/of/Parsoid:/my/path/to/git/checkout/of/Parsoid

A megfelelő konfiguráció ellenőrzéséhez keresd fel a {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page címet, ahol a $domain a $wgCanonicalServer fájlban megadott hosztnév. (Megjegyzés: a Wikimédia Alapítvány éles kiszolgálói nem teszik elérhetővé a Parsoid REST API-ját a külső hálózat számára.)

Tesztek futtatása

Az összes parser- és Mocha-teszt futtatásához: 

$ composer test

A parserteszteknek már számos beállítása van, amelyek a php bin/parserTests.php --help használatával listázhatók.

Ha a MW_INSTALL_DIR környezeti változó egy konfigurált MediaWiki-telepítésre mutat, az alábbi paranccsal további teszteket is futtathatsz: 

$ composer phan-integrated

Egyszerű wikiszöveg átalakítása

Egyszerű wikiszövegrészleteket a parancssorból alakíthatsz át a bin/ könyvtárban található parse.php szkript használatával: 

$ echo '[[Foo]]' | php bin/parse.php

A parse szkript számos beállítással rendelkezik. A php bin/parse.php --help paranccsal megtekintheted ezek leírását.

A Parsoid hibakeresése (fejlesztőknek)

Hibakeresési tanácsokért lásd: Parsoid/Debugging .

Folyamatos integráció

a Parsoid mindig elérhető könyvtárként, mivel a MediaWiki-mag függősége. De két rész nincs engedélyezve:

  • a Parsoid ServiceWiring
  • a Parsoid külső REST API-ja

A Quibble tesztfuttató engedélyezi ezt, ha azt észleli, hogy a mediawiki/services/parsoid.git a build részeként klónozva lett. Ez esetben:

  • a Wikimedia\Parsoid automatikus betöltőjét a klónozott kódra irányítja (ezzel gyakorlatilag lecserélve a Composer által telepített változatot)
  • betölti a kiterjesztést: wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

A ServiceWiringnek a MediaWiki 1.38-as verziójától kezdve engedélyezve kell lennie.

A REST API elméletileg soha nem kerül be a MediaWikibe: a) éles környezetben soha nem volt nyilvánosan elérhető; ez egy, a megszűnő RESTBase által használt belső API; b) soha nem esett át biztonsági auditon; c) funkciói átfedésben vannak a MediaWiki Enterprise API-éval. A megoldás az lesz, hogy a VisualEditor közvetlenül, a VisualEditor Action API-n keresztül hívja meg a Parsoidot, így elkerülhető egy oda-vissza kérés a REST API-n keresztül.

A kiterjesztés betöltése ezért olyan kerülőmegoldás, amely változásnak kitett felületek használatát teszi lehetővé, és amelyeket egyelőre nem igazán szeretnénk használatra ajánlani.

A Parsoidot ezért a legtöbb esetben nem szabad CI-függőségként hozzáadni; 2021 októberében az egyetlen kivétel a MediaWiki Disambiguator kiterjesztése volt.

A Parsoid kiterjesztésként való betöltése lehetővé teszi, hogy MediaWiki-integrációs tesztfeladatokat futtassunk a mediawiki/services/parsoid.git ellen (például Quibble-t vagy apitestinget), és ellenőrizzük, hogy a Parsoid és a MediaWiki megfelelően működik-e együtt.

Egy kiterjesztés akkor is írhat Parsoidot használó teszteket, ha a tároló nincs klónozva. Mivel a MediaWiki magjának Composer-függősége, a MediaWiki\Parsoid névtér elérhető, a szolgáltatásbekötési rész azonban nem (ez a Parsoid tárolójában a extension/src fájlban található, és a \MWParsoid névtéren keresztül érhető el). A ParsoidTestFileSuite.php kód csak akkor futtatja a parserteszteket, ha a Parsoid be van töltve (ami a MediaWiki 1.38-tól kezdve várhatóan alapértelmezett).

A CI-ben a Parsoidot a MediaWiki legfrissebb fejlesztői változatával tesztelik, míg a MediaWikit a Composer-függőségként telepített Parsoiddal. Visszafelé nem kompatibilis változtatás esetén először a Parsoid módosítását olvasztják be (ami a Parsoid CI-jét megszakítja, a MediaWikiét azonban nem), majd a Parsoid frissítésekor hozzáigazítják a MediaWikit. Ez tehát egyirányú változtatás.

Kiadási változat

A MediaWiki kiadási buildjeiben a Parsoid ServiceWiring integrálva van a VisualEditorbe, hogy a VisualEditor további konfiguráció nélkül működjön (a wfLoadExtension( 'VisualEditor' ) kivételével). A kiadási build a REST API-t is engedélyezi, és mindent összekapcsol, hogy a Parsoid azonnal használható legyen. Ehhez a Parsoid kódjának egy részét átmásolják a VisualEditorbe; ez a kód nem szerepel a VisualEditor master ágában, mivel a Parsoid frissítésekor azonnal elavulna. Ehelyett a kódot két helyen tartják karban.

Műszaki leírások

History

The original application was written in JavaScript (using Node.js) and started running on the Wikimedia cluster in December 2012. In 2019, Parsoid was ported to PHP, and the PHP version replaced the JS version on the Wikimedia cluster in December 2019. Parsoid is being integrated into core MediaWiki, with the goal of eventually replacing MediaWiki's current native parser. In early 2024, Parsoid began to be used on some production wikis of the Wikimedia Foundation as the default parser for read views. You can see them in the production config list.

Parsoid (the PHP version) has been natively bundled with MediaWiki since version 1.35, released in September 2020. For non-Wikimedia installations, Parsoid/JS was supported until the end-of-life of MediaWiki 1.31 (LTS) in September 2021.

FAQ

  • How do I see if a page was rendered with Parsoid?
    • The footer will say "Page was rendered with Parsoid".
  • How do I set a page to temporarily render with Parsoid?
  • How do I get an entire wiki to render with Parsoid?
    • Install Extension:ParserMigration
    • Set $wgParserMigrationEnableParsoidArticlePages = true;
    • Set $wgParserMigrationEnableParsoidDiscussionTools = true;
  • Which Wikimedia wikis render with Parsoid?
    • The list is at parsoidrendered.dblist. As of August 2025, it is approximately 250 of the 1000 wikis. Rollout will continue until all wikis are using Parsoid.

See also

Contact

If you need help or have questions/feedback, you can contact us in #mediawiki-parsoid kapcsolódás or the wikitext-l mailing list. If all that fails, you can also contact us by email at content-transform-team at the wikimedia.org domain.

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