CLI de Pré-visualização

Use a CLI de pré-visualização do Potato para validar configurações YAML, inspecionar esquemas de anotação e renderizar uma pré-visualização estática da sua interface sem iniciar o servidor completo.

A CLI de pré-visualização valida configurações de anotação e mostra como os esquemas serão renderizados sem executar o servidor completo. Isso é útil para prototipagem rápida, depuração e validação em CI/CD.

Visão Geral

A CLI de pré-visualização oferece:

Validação de configuração: Verifica erros e avisos antes da implantação
Pré-visualização de esquema: Mostra como os esquemas de anotação serão renderizados em HTML
Detecção de conflitos de atalhos: Identifica atalhos de teclado conflitantes
Vários formatos de saída: Resumo, HTML, JSON ou trechos somente de layout

Uso Básico

bash

# Default summary output
python -m potato.preview_cli config.yaml
 
# Or using the module directly
python -m potato.preview_cli path/to/your/config.yaml

Formatos de Saída

Resumo (Padrão)

Exibe um resumo em texto da configuração:

bash

python -m potato.preview_cli config.yaml

Saída:

text

============================================================
ANNOTATION TASK PREVIEW
============================================================
Task Name: Sentiment Annotation
Task Directory: ./my_task

Validation: PASSED

ANNOTATION SCHEMAS (2 total):
----------------------------------------
  [radio] sentiment
          Select the sentiment of the text...
          Labels: 3
          Keybindings: 3

  [multiselect] topics
          Select all relevant topics...
          Labels: 5
          Keybindings: 0

============================================================

Saída HTML

Gera uma pré-visualização de página HTML completa:

bash

python -m potato.preview_cli config.yaml --format html > preview.html

Abra preview.html em um navegador para ver como seus esquemas de anotação ficarão.

Saída JSON

Gera uma saída JSON estruturada para processamento programático:

bash

python -m potato.preview_cli config.yaml --format json

HTML Somente de Layout

Gera apenas o trecho HTML do esquema de anotação:

bash

python -m potato.preview_cli config.yaml --layout-only > task_layout.html

Isso é útil para incorporar em modelos personalizados ou testar a renderização do esquema isoladamente.

Opções de Linha de Comando

Opção	Abreviação	Descrição
`--format`	`-f`	Formato de saída: `summary`, `html` ou `json`
`--layout-only`	`-l`	Gera apenas o trecho HTML do layout da tarefa
`--verbose`	`-v`	Ativa a saída detalhada/de depuração

Validação de Configuração

A CLI de pré-visualização valida sua configuração e relata problemas:

Erros (Bloqueantes)

text

ERROR: Missing required field 'annotation_task_name'
ERROR: Must have either 'data_files' or 'data_directory'

Avisos (Não Bloqueantes)

text

WARNING: No annotation schemes found in configuration
WARNING: Key '1' used by both 'schema1:Label1' and 'schema2:Label2'

Códigos de Saída

0: A configuração é válida
1: A configuração tem erros

Use os códigos de saída em pipelines de CI/CD:

bash

python -m potato.preview_cli config.yaml || echo "Config validation failed"

Casos de Uso

Prototipagem Rápida

Itere rapidamente em designs de esquema:

bash

# Edit config, then preview immediately
python -m potato.preview_cli config.yaml --format html > preview.html && open preview.html

Integração com CI/CD

Valide configurações no seu pipeline de implantação:

yaml

# .github/workflows/validate.yml
- name: Validate Potato Config
  run: python -m potato.preview_cli configs/production.yaml

Desenvolvimento de Modelos

Gere trechos de layout para integração com modelos personalizados:

bash

python -m potato.preview_cli config.yaml --layout-only > templates/includes/schemas.html

Referência da API

As funções da CLI de pré-visualização também podem ser usadas programaticamente:

python

from potato.preview_cli import (
    load_config,
    validate_config,
    get_annotation_schemes,
    detect_keybinding_conflicts,
    generate_preview_html,
)
 
# Load and validate
config = load_config("config.yaml")
issues = validate_config(config)
 
# Extract schemes and check for conflicts
schemes = get_annotation_schemes(config)
conflicts = detect_keybinding_conflicts(schemes)
 
# Generate output
html = generate_preview_html(schemes)

Solução de Problemas

Erro "Module not found"

Verifique se o Potato está instalado:

bash

pip install potato-annotation

Erros de Renderização de Esquema

Se um esquema não conseguir ser renderizado, a saída incluirá uma mensagem de erro. Verifique se a configuração do seu esquema está completa.

Leitura Adicional

Noções Básicas de Configuração - Referência completa de configuração
Esquemas de Anotação - Tipos de esquema de anotação
Configuração da Interface - Personalizando a interface

Para detalhes de implementação, consulte a documentação de origem.