Jump to content

Parsoid

Hlášení problémů: #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 100% complete.
Languages:
Projekty Wikimedia Foundation
Parsoid
Obousměrný runtime analyzátor wikitextu. Převádí tam a zpět mezi wikitextem a HTML/XML DOM pomocí RDFa.
Skupina: Content Transform Team
Začal: 2011-10
Členové týmu: Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Otto Šleger, Subramanya Sastry, Yiannis Giannelos
Historie změn: #parsoid
Vedoucí: C.Scott Ananian
Vedení: Sérgio Lopes
Aktualizace: Parsoid/Releases
Postup: Parsoid/Deployments
Schéma běhového prostředí Parsoid HTML5 + RDFa wiki

Pro informace ohledně starší verze Parsoidu napsané v Javascriptu (Node.js), navštivte Parsoid/JS .

Parsoid je PHP knihovna spojená s MediaWiki (1.35+), která se používá pro převod tam a zpět mezi wikitextem a HTML. Ve vývoji je již od roku 2012, byl původně napsán v Javascriptu a byl navržen pro podporu VisualEditor . Je součástí MediaWiki od verze 1.35. V MediaWiki 1.47 se plánuje, že Parsoid se stane výchozím parserem MediaWiki a nahradí současný nativní parser v rámci projektu známého jako sjednocení parserů .

Technické podrobnosti

Parsoid je aplikace, která dokáže překládat syntaxi wikitextu z MediaWiki a ekvivalentní model dokumentu HTML/RDFa s vylepšenou podporou pro automatizované zpracování a bohaté úpravy.

Vyvíjí ho tým Wikimedia Foundation od roku 2012. V současné době je hojně využíván aplikacemi VisualEditor , Překlad a dalšími.

Parsoid má za cíl poskytovat bezchybnou konverzi tam a zpět, tj. zabránit ztrátě informací a také zabránit "nečistým rozdílům".

Na wiki stránkách Wikimedie je Parsoid v současné době pro několik aplikací využíván jako proxy za objektem RESTBase , který ukládá HTML přeložený Parsoidem. Očekává se, že RESTBase bude nakonec nahrazena mezipamětí těsněji integrovanou s MediaWiki.

Více informací o celém projektu naleznete v příspěvku na blogu z března 2013. Chcete-li si přečíst o použitém modelu HTML, podívejte se na MediaWiki DOM spec.

Parsoid byl původně strukturován jako webová služba a napsán v JavaScriptu s využitím platformy Node.js. Technická přednáška z února 2019 (slejdy) a příspěvek na blogu popisují proces portování do PHP. Rozšíření API Parsoid je v současné době ve fázi aktivního vývoje; tuto práci popisuje technická přednáška ze srpna 2020.

Repozitáře na GitHubu: https://github.com/wikimedia/parsoid

Použití

Instalace

Toto rozšíření je součástí MediaWiki 1.35 a vyšší. Zbývající konfigurační pokyny je stále nutné dodržovat.

Parsoid je součástí MediaWiki od verze 1.35. K jeho aktivaci není nutná žádná konfigurace.

Parsoid exportuje interní REST API, které historicky používal RESTBase a nebylo přístupné mimo interní cluster WMF. Toto již není vyžadováno pro vizuální editor ani pro zobrazení čtení jádra a interní API je zastaralé a jeho odstranění je plánováno v MW 1.43.

Parsoid je nominálně knihovna pro skládání textů používaná jádrem MediaWiki. Pokud z nějakého důvodu stále potřebujete interní API, můžete Parsoid explicitně načíst "jako rozšíření" přidáním následujícího do LocalSettings.php: 

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

Všem zbývajícím uživatelům interního rozhraní Parsoid API třetích stran důrazně doporučujeme migrovat na hlavní koncový bod stránky REST HTML, který poskytuje ekvivalentní funkce.

Vývoj

Vývoj probíhá v rámci Parsoid Git repository. Kontrola kódu probíhá v Gerritu. Chcete-li si založit účet, podívejte se na Gerrit/Začínáme.

Pokud používáte vývojové prostředí MediaWiki-Vagrant s virtuálním strojem, můžete do něj jednoduše přidat roli visualeditor a nastaví se funkční Parsoid spolu s Extension:VisualEditor .

Níže uvedené pokyny platí pro MediaWiki 1.35 nebo novější. Zaškrtněte Parsoid/JS , pokud používáte starou verzi Parsoidu napsanou v JavaScriptu, která se používá pro MW 1.34 a starší verze.

Propojení vývojářského checkoutu Parsoidu

Ve standardní instalaci MediaWiki je Parsoid součástí MediaWiki jako tvůrčí knihovna, wikimedia/parsoid.

Pro účely vývoje obvykle chcete použít git checkout Parsoidu, a ne verzi, která je součástí jádra MediaWiki jako knihovna pro tvorbu textů. Následující řádky přidané do LocalSettings.php umožňují použití git checkoutu Parsoidu (volitelné), načtení Parsoid REST API s wfLoadExtension (místo použití verze dodávané ve VisualEditoru) a ruční provedení konfigurace Parsoidu, kterou obvykle provádí VisualEditor: 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # svázaná kopie
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// Pro vývojáře: Ujistěte se, že Parsoid je spuštěn z adresáře $parsoidInstallDir,
// (nejedná se o verzi, která je standardně zahrnuta v mediawiki-core)
// Musí se objevit *před* wfLoadExtension()
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // Zachycovat pouze třídy jmenného prostoru Parsoid
        if ( preg_match( '/(MW|Wikimedia\\\\)Parsoid\\\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // Funkce AutoLoader::registerNamespaces byla přidána v MW 1.39.
    AutoLoader::registerNamespaces( [
        // Udržujte to synchronizované s klauzulí "autoload" (automatické načítání) v
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src/",
    ] );
}

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

Tyto řádky nejsou nezbytné pro většinu uživatelů VisualEditoru, kteří mohou používat automatickou konfiguraci VisualEditoru a kód Parsoid, který je součástí MediaWiki, ale budou vyžadovány pro většinu vývojářů.

Pokud používáte MediaWiki s Nginxem, budete muset do bloku serveru přidat také něco podobného (za předpokladu, že soubory vaší instalace MediaWiki jsou umístěny v /w/): 

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

Pokud používáte Mediawiki pomocí Dockeru a propojujete svůj lokální repozitář Parsoid s Mediawiki, je třeba namapovat další svazek na kontejner Docker v souboru docker-compose.override.yml v projektu Media Wiki. Nejjednodušší způsob, jak to provést, je vytvořit soubor docker-compose.override.yml v projektu mediawiki a vložit do něj níže uvedený kód (s úpravou cesty). Pokud již máte soubor docker-compose.override.yml, upravte jej odpovídajícím způsobem. 

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

Pro otestování správné konfigurace navštivte stránku {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page, kde $domain je název hostitele ve vašem souboru $wgCanonicalServer. (Vezměte na vědomí, že produkční servery WMF nezpřístupňují rozhraní Parsoid REST API externí síti.)

Spouštění testů

Spuštění všech testů parseru a mocha testů: 

$ composer test

Testy parseru nyní mají poměrně dost možností, které lze vypsat pomocí php bin/parserTests.php --help.

Pokud máte proměnnou prostředí MW_INSTALL_DIR odkazující na nakonfigurovanou instalaci MediaWiki, můžete spustit několik dalších testů pomocí: 

$ composer phan-integrated

Konverze jednoduchého wikitextu

Jednoduché úryvky wikitextu můžete převést z příkazového řádku pomocí skriptu parse.php v adresáři bin/: 

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

Parse skript má spoustu možností. php bin/parse.php --help vám o tomto poskytne informace.

Ladění Parsoidu (určeno vývojářům)

Tipy pro ladění naleznete v článku Parsoid/Debugging .

Kontinuální integrace

Parsoid je vždy k dispozici jako knihovna, protože je závislostí jádra MediaWiki na editoru. Dvě části však nejsou povoleny:

  • Parsoid ServiceWiring
  • Externí REST API Parsoidu

Testovací runner Quibble by to povolil, pokud by zjistil, že mediawiki/services/parsoid.git byl naklonován jako součást sestavení. V takovém případě:

  • Odkazuje autoloader pro Wikimedia\Parsoid na klonovaný kód (efektivně nahrazuje verzi nainstalovanou composterem)
  • Načíst rozšíření wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

ServiceWiring by měl být v MediaWiki povolen od verze 1.38.

REST API by teoreticky nikdy nebylo začleněno do MediaWiki: a) nikdy nebylo veřejně dostupné v produkčním prostředí, jedná se o interní API používané RESTBase, které končí; b) nikdy nebylo bezpečnostním auditem a c) je redundantní s podnikovým MediaWiki API. Řešením bude, aby VisualEditor volal Parsoid přímo přes VisualEditor Action API, což by ušetřilo zpoždění přes REST API.

Načtení rozšíření je tedy hack, který umožňuje používat rozhraní, která se mohou změnit a která zatím nechceme, aby lidé používali.

Pro většinu účelů by tedy parsoid neměl být přidáván jako závislost CI, jedinou výjimkou od října 2021 je rozšíření Disambiguator MediaWiki.

Načtení parsoidu jako rozšíření nám umožňuje spustit testovací úlohy integrace MediaWiki proti mediawiki/services/parsoid.git (například Quibble, apitesting) a zajistit, aby Parsoid a MediaWiki fungovaly společně.

Rozšíření může být schopno psát testy s Parsoidem, i když repozitář nebyl naklonován. Protože se jedná o závislost jádra MediaWiki na editoru, je jmenný prostor MediaWiki\Parsoid dostupný, ale část pro zapojení služeb nikoli (v repozitáři Parsoid je extension/src a je vystaven jako jmenný prostor \MWParsoid). Kód ParsoidTestFileSuite.php by spustil testy parseru, pouze pokud byl načten Parsoid (což by mělo být výchozí nastavení v MediaWiki 1.38).

V případě CI je Parsoid testován s hrotem MediaWiki, zatímco MediaWiki je testována se závislostí Composeru. V případě zásadní změny se změna v Parsoidu sloučí jako první (což naruší její CI, ale ne změnu v MediaWiki) a MediaWiki se upraví při aktualizaci Parsoidu. Jde tedy o jednosměrnou změnu.

Vydání sestavení

Pro verze MediaWiki máme integraci Parsoid ServiceWiring do VisualEditoru, aby VisualEditor fungoval bez další konfigurace (kromě wfLoadExtension( 'VisualEditor' )). Verze Release také umožňuje REST API a propojení všech funkcí, takže Parsoid funguje ihned po instalaci. To se provede zkopírováním části kódu Parsoidu do VisualEditoru, která se nenachází v větvi master VisualEditoru, protože by byla zastaralá, jakmile bude Parsoid aktualizován. Místo toho je kód uchováván na dvou místech.

Technická dokumentace

Odkazy pro vývojáře Parsoidu

Odkazy pro nasazení Parsoidu (do klastru Wikimedia)

Historie

Původní aplikace, která byla napsána v JavaScriptu (používala Node.js), se začala používat v rámci clusteru Wikimedie v prosinci 2012. V roce 2019 byl Parsoid přepracován do PHP kódu a tato verze nahradila původní javascriptovou verzi v rámci clusteru Wikimedie v prosinci 2019. Parsoid je připravován k začlenění do jádra MediaWiki a aby mohl nahradit současný nativní parser MediaWiki. To je cíl. Začátkem roku 2024 se Parsoid začal používat na některých produkčních wikin Wikimedia Foundation jako výchozí analyzátor pro zobrazení pro čtení. Můžete si je prohlédnout v seznamu konfigurace produkční verze.

Parsoid (verze pro PHP) je nativní součástí MediaWiki od verze 1.35, vydané v září 2020. Pro instalace mimo Wikimedii byl Parsoid/JS podporován až do konce životnosti MediaWiki 1.31 (LTS) v září 2021.

Časté dotazy

  • Jak zjistím, zda byla stránka vykreslena pomocí Parsoidu?
    • V zápatí bude uvedeno "Stránka byla vykreslena pomocí Parsoidu".
  • Jak nastavím stránku tak, aby se dočasně vykreslovala pomocí Parsoidu?
  • Jak můžu v Parsoidu vykreslit celou wiki?
    • Nainstalujte Extension:ParserMigration
    • Sada $wgParserMigrationEnableParsoidArticlePages = true;
    • Sada $wgParserMigrationEnableParsoidDiscussionTools = true;
  • Které wiki stránky Wikimedie se vykreslují pomocí Parsoidu?
    • Seznam je na parsoidrendered.dblist. K srpnu 2025 je to přibližně 250 z 1000 wikin. Zavádění bude pokračovat, dokud všechny wikiny nebudou používat Parsoid.

Související odkazy

Externí odkazy

Kontakt

Pokud potřebujete pomoc nebo máte dotazy/zpětnou vazbu, můžete nás kontaktovat na adrese #mediawiki-parsoid připojit se nebo e-mailový seznam wikitext-l. Pokud ani toto selže, můžete nás kontaktovat e-mailem na adrese content-transform-team na doméně wikimedia.org.

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