Jump to content

Parsoid

No rastreador: #parsoid
From mediawiki.org
This page is a translated version of the page Parsoid and the translation is 99% complete.
Languages:
Projetos da Fundação Wikimedia
Parsoid
Um interpretador bidirecional de wikitexto. Converte bidirecionalmente entre wikitexto e DOM HTML/XML com RDFa.
Grupo: Content Transform Team
Início: 2011-10
Membros da equipe: Arlo Breault, C.Scott Ananian, Isabelle Hurbain-Palatin, Mateus Santos, Otto Šleger, Subramanya Sastry, Yiannis Giannelos
Backlog: #parsoid
Líder: C.Scott Ananian
Gestão: Sérgio Lopes
Atualização: Parsoid/Releases
Progresso: Parsoid/Deployments
Um diagrama do ambiente de execução wiki Parsoid HTML5 + RDFa

"Para a versão mais antiga do Parsoid escrita em JavaScript (Node.js), consulte Parsoid/JS ."

Parsoid é uma biblioteca PHP incluída no MediaWiki (desde a versão 1.35) que é usada para converter entre wikitexto e HTML. Está em desenvolvimento desde 2012, tendo sido originalmente escrito em JavaScript e criado para suportar o VisualEditor . It has been bundled with MediaWiki since version 1.35. In MediaWiki 1.47, Parsoid is planned to become MediaWiki's default parser, replacing the current native parser , in a project known as parser unification .

Detalhes técnicos

O Parsoid é um aplicativo capaz de converter, em ambos os sentidos, entre a sintaxe wikitexto do MediaWiki e um modelo de documento HTML/RDFa equivalente, com suporte aprimorado para processamento automatizado e edição avançada.

Está sendo desenvolvido por uma equipe da Fundação Wikimedia desde 2012. Atualmente, é amplamente utilizado pelo VisualEditor , pelo Tradutor de conteúdo e por outras aplicações.

O Parsoid foi concebido para proporcionar uma conversão bidirecional perfeita, ou seja, para evitar a perda de informações e também impedir a ocorrência de "diferenças incorretas".

Nas wikis da Wikimedia, para várias aplicações, o Parsoid está atualmente configurado como proxy por meio do RESTBase , que armazena o HTML traduzido pelo Parsoid. Espera-se que o RESTBase venha a ser substituído por um cache mais integrado ao MediaWiki.

Para saber mais sobre o projeto como um todo, consulte esta publicação no blog de março de 2013. Para saber mais sobre o modelo HTML utilizado, consulte Especificação DOM do MediaWiki.

O Parsoid foi originalmente concebido como um serviço web e escrito em JavaScript, utilizando o Node.js. Uma [palestra técnica de fevereiro de 2019] (slides) e postagem no blog descrevem o processo de portá-la para PHP. A API de extensão do Parsoid está atualmente em desenvolvimento ativo; uma palestra técnica de agosto de 2020 descreve esse trabalho.

Repositório do GitHub: https://github.com/wikimedia/parsoid

Uso

Instalação

Esta extensão vem com o MediaWiki 1.35 e versões superiores. The remaining configuration instructions must still be followed.

O Parsoid está incluído no MediaWiki desde a versão 1.35. Não é necessária nenhuma configuração para ativá-lo.

O Parsoid exporta uma API REST interna que, historicamente, era utilizada pelo RESTBase e não era acessível fora do cluster interno da WMF. Isso não é mais necessário para o Editor Visual ou para as visualizações de leitura do núcleo, e a API interna está sendo descontinuada, com remoção prevista para a versão MW 1.43.

O Parsoid é, em princípio, uma biblioteca de compositores utilizada pelo núcleo do MediaWiki. Se, por algum motivo, você ainda precisar da API interna, poderá carregar explicitamente o Parsoid “como uma extensão” adicionando o seguinte ao LocalSettings.php: 

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

Recomenda-se enfaticamente que todos os usuários terceirizados que ainda utilizam a API interna do Parsoid migrem para o endpoint REST da página HTML principal, que oferece funcionalidades equivalentes.

Desenvolvimento

O desenvolvimento ocorre no Parsoid Git repository. A revisão de código é feita no Gerrit. Consulte Gerrit/Introdução para criar uma conta.

Se você usar o ambiente de desenvolvimento de MediaWiki-Vagrant em uma máquina virtual, basta adicionar a função visualeditor a ele, e ele configurará um Parsoid funcional junto com Extension:VisualEditor .

As instruções abaixo se aplicam ao MediaWiki 1.35 ou versões posteriores. Marque a opção Parsoid/JS se estiver executando a versão antiga do Parsoid, escrita em JavaScript e usada no MW 1.34 e versões anteriores.

Vinculando uma versão de checkout para desenvolvedores do Parsoid

Em uma instalação padrão do MediaWiki, o Parsoid é incluído pelo MediaWiki como uma biblioteca do Composer, wikimedia/parsoid.

Para fins de desenvolvimento, geralmente é recomendável usar uma cópia do Parsoid obtida via git checkout, e não a versão incluída no núcleo do MediaWiki como uma biblioteca do Composer. As linhas a seguir, adicionadas ao LocalSettings.php , permitem fazer um checkout do Parsoid no Git (opcionalmente), carregar a API REST do Parsoid com o wfLoadExtension (em vez de usar a versão incluída no VisualEditor) e realizar manualmente a configuração do Parsoid, que normalmente é feita pelo VisualEditor: 

$parsoidInstallDir = 'vendor/wikimedia/parsoid'; # cópia incluída
#$parsoidInstallDir = '/my/path/to/git/checkout/of/Parsoid';

// Para desenvolvedores: certifiquem-se de que o Parsoid seja executado a partir de $parsoidInstallDir,
// (não é a versão incluída por padrão no mediawiki-core)
// Deve ocorrer *antes* de wfLoadExtension()
if ( $parsoidInstallDir !== 'vendor/wikimedia/parsoid' ) {
    function wfInterceptParsoidLoading( $className ) {
        // Interceptar apenas as classes do namespace Parsoid
        if ( preg_match( '/(MW|Wikimedia\\\\)Parsoid\\\\/', $className ) ) {
           $fileName = Autoloader::find( $className );
           if ( $fileName !== null ) {
               require $fileName;
           }
        }
    }
    spl_autoload_register( 'wfInterceptParsoidLoading', true, true );
    // Foi adicionado AutoLoader::registerNamespaces na versão 1.39 do MW
    AutoLoader::registerNamespaces( [
        // Mantenha isso em sincronia com a cláusula "autoload" em
        // $parsoidInstallDir/composer.json
        'Wikimedia\\Parsoid\\' => "$parsoidInstallDir/src/",
    ] );
}

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

Essas linhas não são necessárias para a maioria dos usuários do VisualEditor, que podem utilizar a configuração automática do VisualEditor e o código do Parsoid incluído no MediaWiki, mas serão necessárias para a maioria dos desenvolvedores.

Se você estiver hospedando o MediaWiki com o Nginx, será necessário adicionar algo como isto no seu bloco de servidor (supondo que a configuração do MediaWiki tenha seus arquivos localizados em /w/): 

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

Se você estiver executando o MediaWiki usando o Docker e vinculando seu repositório local do Parsoid ao MediaWiki, será necessário mapear um volume adicional para o contêiner do Docker no arquivo docker-compose.override.yml do projeto do MediaWiki. Para isso, a maneira mais simples é criar uma pasta chamada docker-compose.override.yml no projeto MediaWiki e inserir o código abaixo nela (após modificar o caminho). Se você já tiver o arquivo docker-compose.override.yml, modifique-o conforme necessário. 

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

Para verificar se a configuração está correta, acesse {$wgScriptPath}/rest.php/{$domain}/v3/page/html/Main%20Page, sendo que $domain é o nome do host no seu $wgCanonicalServer. (Observe que os servidores WMF em produção não expõem a API REST do Parsoid à rede externa.)

Executando os testes

Para executar todos os testes do analisador e os testes do Mocha: 

$ composer test

Os testes do analisador contam agora com várias opções, que podem ser listadas usando php bin/parserTests.php --help.

Se a variável de ambiente MW_INSTALL_DIR estiver apontando para uma instalação configurada do MediaWiki, você pode executar alguns testes adicionais com: 

$ composer phan-integrated

Conversão de wikitexto simples

Você pode converter trechos simples de wikitexto a partir da linha de comando usando o script parse.php no diretório bin/: 

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

O script de análise tem várias opções. php bin/parse.php --help fornece informações sobre isso.

Depuração do Parsoid (para desenvolvedores)

Veja a seção Parsoid/Debugging para dicas de depuração.

Integração contínua

O Parsoid está sempre disponível como biblioteca, uma vez que é uma dependência do Composer do núcleo do MediaWiki. No entanto, dois componentes não estão habilitados:

  • Parsoid ServiceWiring
  • API REST externa do Parsoid

O executor de testes Quibble ativaria essa opção caso detectasse que mediawiki/services/parsoid.git foi clonado como parte da compilação. Nesse caso, isso:

  • direciona o autoloader do Wikimedia\Parsoid para o código clonado (substituindo, na prática, a versão instalada pelo Composer)
  • Carregue a extensão wfLoadExtension( 'Parsoid', '/path/to/cloned/repo' );

O ServiceWiring deve estar habilitado no MediaWiki a partir da versão 1.38.

A API REST, em teoria, nunca seria incorporada ao MediaWiki: a) ela nunca foi disponibilizada ao público em ambiente de produção; trata-se de uma API interna utilizada pelo RESTBase, que está sendo descontinuado; b) ela nunca passou por uma auditoria de segurança; e c) ela é redundante em relação à API empresarial do MediaWiki. A solução seria o VisualEditor invocar o Parsoid diretamente por meio da API de Ações do VisualEditor, o que evitaria uma ida e volta pela API REST.

Carregar a extensão é, portanto, um truque que permite usar interfaces sujeitas a alterações e que, na verdade, ainda não queremos que as pessoas utilizem.

Para a maioria dos casos, o parsoid não deve, portanto, ser adicionado como dependência de CI; a única exceção, em outubro de 2021, é a extensão Disambiguator do MediaWiki.

Carregando o Parsoid como extensão, vamos executar tarefas de teste de integração do MediaWiki no mediawiki/services/parsoid.git (como o Quibble e o apitesting) e garantir que o Parsoid e o MediaWiki funcionem em conjunto.

Uma extensão pode ser capaz de escrever testes com o Parsoid mesmo quando o repositório ainda não tiver sido clonado. Como se trata de uma dependência do núcleo do MediaWiki, o namespace MediaWiki\Parsoid está disponível, mas a parte de integração do serviço não está (ela é extension/src no repositório do Parsoid e exposta como o namespace \MWParsoid). O código de ParsoidTestFileSuite.php só executaria os testes do analisador se o Parsoid tivesse sido carregado (o que deve ser o padrão no MediaWiki 1.38).

No caso do CI, o Parsoid é testado com a versão mais recente do MediaWiki, enquanto o MediaWiki é testado com a dependência do Composer. Em caso de uma alteração compatibilidade, a alteração do Parsoid é incorporada primeiro (o que causa falhas na integração contínua do Parsoid, mas não na do MediaWiki) e o MediaWiki é ajustado quando o Parsoid é atualizado. Trata-se, portanto, de uma mudança irreversível.

Versão de lançamento

Para as compilações de lançamento do MediaWiki, integramos o Parsoid ServiceWiring ao VisualEditor para que este funcione sem necessidade de configuração adicional (além de um wfLoadExtension( 'VisualEditor' )). A versão de lançamento também habilita a API REST e configura tudo para que o Parsoid funcione imediatamente. Isso é feito copiando um trecho do código do Parsoid para o VisualEditor, que não está no ramo principal do VisualEditor, pois ficaria obsoleto assim que o Parsoid fosse atualizado. Em vez disso, o código é mantido em dois locais.

Documentos técnicos

História

O aplicativo original foi escrito em JavaScript (usando Node.js) e começou a ser executado no cluster da Wikimedia em dezembro de 2012. Em 2019, a Parsoid foi portada para PHP, tendo essa versão substituído a em JS na Wikimedia em dezembro de 2019. Essa biblioteca está sendo integrada ao núcleo do MediaWiki, com o objetivo de eventualmente substituir o atual interpretador nativo do MediaWiki. No início de 2024, o Parsoid começou a ser utilizado em algumas wikis de produção da Wikimedia Foundation como o analisador padrão para visualizações de leitura. Você pode vê-los na lista de configuração de produção.

O Parsoid (na versão PHP) vem integrado nativamente ao MediaWiki desde a versão 1.35, lançada em setembro de 2020. Para instalações que não sejam da Wikimedia, o Parsoid/JS teve suporte até o fim do ciclo de vida do MediaWiki 1.31 (LTS) em setembro de 2021.

FAQ

  • Como posso verificar se uma página foi renderizada com o Parsoid?
    • O rodapé exibirá a mensagem "Esta página foi gerada com o Parsoid".
  • Como faço para configurar uma página para ser renderizada temporariamente com o Parsoid?
  • Como faço para renderizar um wiki inteiro com o Parsoid?
    • Instalar Extension:ParserMigration
    • Conjunto de $wgParserMigrationEnableParsoidArticlePages = true;
    • Conjunto de $wgParserMigrationEnableParsoidDiscussionTools = true;
  • Quais wikis da Wikimedia utilizam o Parsoid para renderização?
    • A lista está em parsoidrendered.dblist. Em agosto de 2025, eram cerca de 250 dos 1.000 wikis. A implementação continuará até que todos os wikis estejam usando o Parsoid.

Veja também

Contato

Se precisar de ajuda ou tiver dúvidas/sugestões, entre em contato conosco em #mediawiki-parsoid conectar ou na lista de discussão wikitext-l. Se nada disso funcionar, você também pode entrar em contato conosco por e-mail no endereço content-transform-team no domínio wikimedia.org.

Retrieved from "https://www.mediawiki.org/w/index.php?title=Parsoid/pt-br&oldid=8347039"