Parsoid
Parsoid
雙向運行時維基文本解析器。 使用RDFa在wikitext和HTML/XML DOM之間相互轉換。
|
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
用法
- Parsoid/Releases - Parsoid發布的版本列表
- Parsoid/API - 用於網頁API
- MediaWiki DOM spec - 用於理解您從API獲取的HTML代碼,旨在用作未來的存儲格式
- Parsoid/LanguageConverter - 關於Parsoid實現LanguageConverter 的說明
- Parsoid/Known differences with Core Parser output
安裝
在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/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
Parsoid開發者的相關連結
- 請參閱Parsoid/Debugging了解調試提示。
- 升級或添加軟體包到Parsoid
- 請參閱以下說明,了解如何將Parsoid的解析器測試副本同步到核心/從核心同步
- Parsoid有一個有限的庫接口用於以編程方式調用它。
- 關於重定向擴展以使用Parsoid的技術講座
- 如果您希望將擴展與Parsoid一起使用
- Parsoid HTML規範版本控制
- 如果您要更改Parsoid輸出
對於Parsoid部署者的連結(到維基媒體集群)
- Parsoid/Deployments
- RT testing commits (useful to check regressions and fixes)
- Deployment instructions for Parsoid
- Kibana儀錶盤
- Grafana dashboard for wt2html metrics
- Grafana dashboard for html2wt metrics
- Prometheus breakdown for the Parsoid cluster on eqiad
- Prometheus breakdown for the Parsoid cluster on codfw
- Jenkins Job Builder docs for updating jenkins jobs
參見
- API
- RESTBase: 由Parsoid翻譯的頁面HTML的緩存/存儲API代理
- Parsoid 團隊的季度審查會議:2015年4月,2015年1月(更早)
- Parser 2011/Parser plan: 早期(現在相對較舊)的設計理念和問題
- Special:PrefixIndex/Parsoid/: 此wiki中與Parsoid相關的頁面
- Extension:ParsoidBatchAPI (存檔)
- parsoid-jsapi:用於提取和轉換wikitext的高級接口,類似於mwparserfromhell API。
- 替代解析器
- Parsoid/Parser Unification
外部連結
- 原始碼(GitHub鏡像源)
- JS文檔(舊版Parsoid)
- PHP文件
- 維基媒體共享資源上的Parsoid
聯絡
如果您需要幫助或有問題/反饋,您可以在#mediawiki-parsoid 連線或wikitext-l郵箱列表與我們聯繫。
如果所有這些方式都失敗了,您也可以通過電子郵件與我們聯繫,地址為wikimedia.org
域名的content-transform-team
。
Parsoid由the Content Transform Team維護。
取得協助:
|