[go: nahoru, domu]
Jump to content

Parsoid

問題追蹤器： #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 79% complete.
Languages:
維基媒體基金會的專案
Parsoid
雙向運行時維基文本解析器。 使用RDFa在wikitext和HTML/XML DOM之間相互轉換。
群組： Content Transform Team
開始： 2011-10
成員： Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Shannon Bailey, Yiannis Giannelos
主導： Subramanya Sastry
管理： Sérgio Lopes
對Parsoid HTML5 + RDFa wiki運行時的藝術構想

Parsoid是一個允許在wikitext和HTML之間來迴轉換的庫。 原始應用程式是用JavaScript編寫的（藉助Node.js），並自2012年12月起在維基媒體集群上運行。 在2019年，Parsoid移植到PHP，維基媒體集群於2019年12月以PHP版本取代了JS版本。 Parsoid已經集成到MediaWiki核心，其目標是最終取代MediaWiki當前的本地解析器。 In early 2024, Parsoid began to be used on some production wikis as the default parser for read views.

Parsoid (PHP版本) 已經原生捆綁到2020年9月發布的MediaWiki版本1.35或更高版本中。 對於非維基媒體安裝，Parsoid/JS在2021年9月MediaWiki 1.31（LTS）生命周期結束之前一直受支持。 The legacy parser will still be supported in MediaWiki 1.43 (LTS).

技術細節

Parsoid是一個應用程式，可以在MediaWiki的wiki文本語法和等效的HTML/RDFa文檔模型之間來迴轉換，並增強了對自動處理和豐富編輯的支持。

自2012年以來，它一直由維基媒體基金會的一個團隊開發。 它目前被VisualEditor 、Structured discussions 、內容翻譯 和其他應用廣泛使用。

Parsoid旨在提供完美的來迴轉換，即避免信息丟失並防止「髒差異」。

在維基媒體wiki上，對於一些應用程式，Parsoid目前被代理在RESTBase 之後，它存儲了由Parsoid翻譯的HTML。 預計RESTBase最終將被替換，與MediaWiki的緩存更緊密地集成在一起。

有關整個項目的更多信息，請參閱2013年3月的這篇博文。 要了解正在使用的HTML模型，請參閱MediaWiki DOM 規範。

Parsoid最初是作為Web服務構建的，用JavaScript編寫，利用Node.js。 2019年2月的技術講座（幻燈片）和博客文章描述了將其移植到PHP的過程。 Parsoid擴展API目前正在積極開發中；2020年8月的技術講座描述了這項工作。

Github倉庫： https://github.com/wikimedia/parsoid

用法

安裝

在MediaWiki 1.35中，Parsoid/PHP包含在捆綁包中，並由可視化編輯器自動加載。 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.

開發

開發地址在Parsoid Git repository。 代碼審查地址在Gerrit。 請參閱Gerrit/教程為自己創建一個帳戶。

如果您使用虛擬機的MediaWiki-Vagrant 開發環境，您只需將角色visualeditor添加到其中，它就會與Extension:VisualEditor 一起設置一個工作的Parsoid。 （這可能已被切換到Parsoid/PHP時被打破：T258940）

請注意，最近發布的Parsoid版本是用PHP編寫的，Parsoid/PHP的安裝嚮導如下所述。 如果您運行的是MediaWiki 1.35或更高版本，則應使用此功能。 如果您運行的是用JavaScript編寫的舊版本的Parsoid，並且用於MW 1.34及更早版本，請查閱Parsoid/JS。

連結Parsoid的開發人員簽出

在標準的MediaWiki安裝中，Parsoid作為一個composer庫wikimedia/parsoid在MediaWiki中包含。

出於開發目的，您通常希望使用Parsoid的git簽出，而不是MediaWiki核心中捆綁的版本作為composer庫。 以下添加到LocalSettings.php 的行允許使用Parsoid的git簽出（可選），以wfLoadExtension 加載Parsoid REST API（而不是使用可視化編輯器中捆綁的版本），並手動執行通常由可視化編輯器完成的Parsoid配置： 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # 捆绑包副本
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// 写给开发人员：确保Parsoid从$parsoidInstallDir执行，
// （不是默认包含在mediawiki-core中的版本）
// 必须在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 );
    // 在MW 1.39中添加了AutoLoader::registerNamespaces
    AutoLoader::registerNamespaces( [
        // 与下文的“autoload”子句保持同步
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src",
    ] );
}

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

# 手动配置Parsoid
$wgVisualEditorParsoidAutoConfig = false;
$wgParsoidSettings = [
    'useSelser' => true,
    'rtTestMode' => false,
    'linting' => false,
];
$wgVirtualRestConfig['modules']['parsoid'] = [
    // Parsoid实例的URL。
    // 如果Parsoid未在本地运行，则应更改$wgServer以匹配非本地主机 
    // 在macOS中使用Docker时，可能需要将$wgServer替换为http://host.docker.internal:8080
    // 在linux中使用Docker时，可能需要将$wgServer替换为http://172.17.0.1:8080
    'url' => $wgServer . $wgScriptPath . '/rest.php',
    // Parsoid“域名”，见下文（可选，很少需要）
    // 'domain' => 'localhost',
];
unset( $parsoidInstallDir );

對於大多數可視化編輯器用戶來說，這些行不是必需的，他們可以使用自動配置以及MediaWiki 1.35和可視化編輯器中包含的捆綁的Parsoid代碼，但對於大多數開發人員來說，這些行是必需的。

如果您使用Nginx為MediaWiki提供服務，則還需要在伺服器塊中添加類似這樣的東西（假設您的MediaWiki設置的文件位於/w/）： 

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

要測試正確的配置，請訪問{$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page，其中$domain是$wgCanonicalServer中的主機名。 （請注意，生產WMF伺服器不會向外部網絡公開Parsoid REST API。

運行測試

要運行所有解析器測試和mocha測試，請執行以下操作： 

$ composer test

解析器測試現在有很多選項，可以使用php bin/parserTests.php --help命令列出。

如果您的環境變量MW_INSTALL_DIR指向已配置的MediaWiki安裝，則可以使用以下命令運行一些額外的測試： 

$ composer phan-integrated

轉換簡單的wikitext

您可以使用bin/目錄中的parse.php腳本從命令行轉換簡單的wikitext片段： 

echo 'Foo' | php bin/parse.php

解析腳本有很多選項。 php bin/parse.php --help命令能為您提供相關信息。

調試Parsoid（對於開發人員）

請參閱Parsoid/Debugging 了解調試提示。

持續集成

截至2021年10月

Parsoid始終可以作為庫使用，因為它是MediaWiki核心的composer依賴項。但有兩個部分未啟用：

  • Parsoid ServiceWiring
  • Parsoid的外部REST api

如果測試運行程序Quibble檢測到mediawiki/services/parsoid.git已被克隆為構建的一部分，它將啟用它。 在此情況下，它：

  • 為Wikimedia\Parsoid將自動加載器指向克隆的代碼（有效地替換了composer安裝的版本）
  • 載入擴展 wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

從1.38開始，應在MediaWiki中啟用ServiceWiring。

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. The solution will be for VisualEditor to invoke Parsoid directly via the VisualEditor Action API which would save a round trip through the REST API.

Loading the extension is thus a hack which enables using interfaces subject to change and which we don't really want people to use yet.

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.

Loading parsoid as an extension let us run MediaWiki integration test jobs against mediawiki/services/parsoid.git (such as Quibble, apitesting) and ensure Parsoid and MediaWiki work together.

An extension may be able to write tests with Parsoid even when the repository has not been cloned. Since it is a composer dependency of MediaWiki core the MediaWiki\Parsoid namespace is available, but the service wiring part is not (it is extension/src in the Parsoid repository and exposed as the \MWParsoid namespace). The ParsoidTestFileSuite.php code would only run the parser tests if Parsoid has been loaded (which should be the default with MediaWiki 1.38).

For CI, Parsoid is tested against the tip of mediawiki, whereas mediawiki is tested with the composer dependency. 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. It is thus a one way change.

發布版本

For MediaWiki release builds, we have an integration of Parsoid ServiceWiring into VisualEditor in order to have VisualEditor work without further configuration (beside a wfLoadExtension( 'VisualEditor' )). The release build also enables the REST API and hook everything us so that parsoid works out of the box. This is done by copying a bit of parsoid code into VisualEditor which is not in the master branch of VisualEditor since that would be obsolete as soon as Parsoid is updated. Instead the code is maintained in two places.

技術文檔

Parsoid開發者的相關連結

對於Parsoid部署者的連結（到維基媒體集群）

參見

外部連結

聯絡

如果您需要幫助或有問題/反饋，您可以在#mediawiki-parsoid 連線或wikitext-l郵箱列表與我們聯繫。 如果所有這些方式都失敗了，您也可以通過電子郵件與我們聯繫，地址為wikimedia.org域名的content-transform-team。

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