From a06f789f4ce101208c85021fd8b2f6380ff94a3b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 16:59:18 +0000 Subject: [PATCH 1/3] Initial plan From d5c547c1b8ff8f6155e41fbd9319d48ef6267b16 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 17:07:19 +0000 Subject: [PATCH 2/3] Add comprehensive end-user documentation for MarkAPI Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com> --- README.md | 12 + docs/user-guide/01-Installation-Guide.md | 295 +++++++++++++++++ docs/user-guide/02-XML-Validation-Guide.md | 353 +++++++++++++++++++++ docs/user-guide/README.md | 217 +++++++++++++ 4 files changed, 877 insertions(+) create mode 100644 docs/user-guide/01-Installation-Guide.md create mode 100644 docs/user-guide/02-XML-Validation-Guide.md create mode 100644 docs/user-guide/README.md diff --git a/README.md b/README.md index 725b37e..512565a 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,18 @@ License: GPLv3 --- +## Documentation for End Users + +📚 **New to MarkAPI?** Check out our comprehensive user guides: + +- **[Installation Guide](docs/user-guide/01-Installation-Guide.md)** - Step-by-step instructions to install MarkAPI +- **[XML Validation Guide](docs/user-guide/02-XML-Validation-Guide.md)** - How to validate XML documents +- **[User Documentation Index](docs/user-guide/README.md)** - Complete documentation overview + +These guides are designed for non-developers and provide detailed instructions in Portuguese for installation and usage. + +--- + ## Development Environment You can use Docker directly or via `make`. To see available commands: diff --git a/docs/user-guide/01-Installation-Guide.md b/docs/user-guide/01-Installation-Guide.md new file mode 100644 index 0000000..5f16c2a --- /dev/null +++ b/docs/user-guide/01-Installation-Guide.md @@ -0,0 +1,295 @@ +# Guia de Instalação do MarkAPI para Usuários + +Este guia apresenta instruções passo a passo para instalar e configurar o MarkAPI em seu servidor, destinado a usuários finais que desejam utilizar a aplicação para validar e converter documentos XML. + +## Pré-requisitos + +Antes de iniciar a instalação, certifique-se de que seu sistema possui: + +1. **Docker** (versão 20.10 ou superior) +2. **Docker Compose** (versão 2.0 ou superior) +3. **Git** (para clonar o repositório) +4. Pelo menos **4GB de RAM** disponível +5. Pelo menos **10GB de espaço em disco** + +### Instalação do Docker + +#### Linux (Ubuntu/Debian) + +```bash +# Atualizar pacotes do sistema +sudo apt-get update + +# Instalar dependências +sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common + +# Adicionar chave GPG oficial do Docker +curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg + +# Adicionar repositório do Docker +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +# Instalar Docker +sudo apt-get update +sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin + +# Verificar instalação +docker --version +docker compose version +``` + +#### Windows + +1. Baixe o **Docker Desktop** em: https://www.docker.com/products/docker-desktop +2. Execute o instalador e siga as instruções na tela +3. Reinicie o computador quando solicitado +4. Abra o Docker Desktop e aguarde sua inicialização + +#### macOS + +1. Baixe o **Docker Desktop** em: https://www.docker.com/products/docker-desktop +2. Abra o arquivo `.dmg` baixado +3. Arraste o ícone do Docker para a pasta Aplicativos +4. Abra o Docker Desktop e aguarde sua inicialização + +## Instalação do MarkAPI + +### Passo 1: Clonar o Repositório + +Abra o terminal e execute: + +```bash +# Clone o repositório do MarkAPI +git clone https://github.com/scieloorg/markapi.git + +# Entre no diretório do projeto +cd markapi +``` + +### Passo 2: Configurar Variáveis de Ambiente + +O MarkAPI utiliza arquivos de configuração para definir parâmetros importantes. Para ambiente de produção: + +```bash +# Copiar arquivos de exemplo +cp -r .envs/.production .envs/.production.backup +``` + +**Importante:** Edite os arquivos em `.envs/.production/` para configurar: + +1. **`.envs/.production/.django`** + - `DJANGO_SECRET_KEY`: Gere uma chave secreta única (use um gerador online) + - `DJANGO_ALLOWED_HOSTS`: Adicione o domínio do seu servidor (ex: `markapi.example.com`) + - `DJANGO_ADMIN_URL`: Personalize a URL do painel administrativo (ex: `admin-secreto/`) + +2. **`.envs/.production/.postgres`** + - `POSTGRES_PASSWORD`: Defina uma senha forte para o banco de dados + +### Passo 3: Criar Diretórios de Dados + +```bash +# Criar diretório para dados do PostgreSQL +mkdir -p ../scms_data/markapi/data_prod +mkdir -p ../scms_data/markapi/data_prod_backup + +# Ajustar permissões +chmod 700 ../scms_data/markapi/data_prod +``` + +### Passo 4: Construir as Imagens Docker + +```bash +# Construir as imagens do MarkAPI +docker compose -f production.yml build +``` + +Este processo pode levar alguns minutos na primeira execução. + +### Passo 5: Inicializar o Banco de Dados + +```bash +# Executar migrações do banco de dados +docker compose -f production.yml run --rm django python manage.py migrate + +# Criar superusuário (usuário administrador) +docker compose -f production.yml run --rm django python manage.py createsuperuser +``` + +Quando solicitado, forneça: +- **Usuário**: seu nome de usuário desejado +- **E-mail**: seu endereço de e-mail +- **Senha**: uma senha forte (será solicitada duas vezes) + +### Passo 6: Coletar Arquivos Estáticos + +```bash +# Coletar arquivos CSS, JavaScript e imagens +docker compose -f production.yml run --rm django python manage.py collectstatic --noinput +``` + +### Passo 7: Iniciar a Aplicação + +```bash +# Iniciar todos os serviços +docker compose -f production.yml up -d +``` + +Os seguintes serviços serão iniciados: +- **Django**: Aplicação web principal +- **PostgreSQL**: Banco de dados +- **Redis**: Cache e fila de mensagens +- **Celery Worker**: Processamento de tarefas em segundo plano +- **Celery Beat**: Agendador de tarefas +- **Traefik**: Proxy reverso (se configurado) + +### Passo 8: Verificar o Status + +```bash +# Verificar se os containers estão rodando +docker compose -f production.yml ps + +# Verificar logs em caso de problemas +docker compose -f production.yml logs django +``` + +## Acessar a Aplicação + +Após a instalação bem-sucedida: + +1. **Interface Web**: Acesse `http://seu-servidor:8000` (ou o domínio configurado) +2. **Painel Administrativo**: Acesse `http://seu-servidor:8000/django-admin/` (ou a URL personalizada) + +Faça login com as credenciais do superusuário criadas no Passo 5. + +## Configuração Opcional: Proxy Reverso (Nginx/Traefik) + +Para ambiente de produção, é recomendado configurar um proxy reverso com HTTPS. + +### Usando Traefik (incluído) + +O MarkAPI já vem configurado com Traefik. Edite o arquivo `.envs/.production/.django` e configure: + +``` +DJANGO_ALLOWED_HOSTS=seu-dominio.com +``` + +Certifique-se de que as portas 80 e 443 estão acessíveis. + +## Comandos Úteis + +### Parar a Aplicação + +```bash +docker compose -f production.yml stop +``` + +### Reiniciar a Aplicação + +```bash +docker compose -f production.yml restart +``` + +### Ver Logs + +```bash +# Logs de todos os serviços +docker compose -f production.yml logs -f + +# Logs de um serviço específico +docker compose -f production.yml logs -f django +docker compose -f production.yml logs -f celeryworker +``` + +### Executar Comandos Django + +```bash +# Template geral +docker compose -f production.yml run --rm django python manage.py + +# Exemplos +docker compose -f production.yml run --rm django python manage.py shell +docker compose -f production.yml run --rm django python manage.py createsuperuser +``` + +### Backup do Banco de Dados + +```bash +# Fazer backup +docker compose -f production.yml exec postgres backup + +# Listar backups +docker compose -f production.yml exec postgres list-backups + +# Restaurar backup +docker compose -f production.yml exec postgres restore +``` + +### Atualizar a Aplicação + +```bash +# Parar a aplicação +docker compose -f production.yml down + +# Atualizar código +git pull origin main + +# Reconstruir imagens +docker compose -f production.yml build + +# Executar migrações +docker compose -f production.yml run --rm django python manage.py migrate + +# Coletar arquivos estáticos +docker compose -f production.yml run --rm django python manage.py collectstatic --noinput + +# Reiniciar aplicação +docker compose -f production.yml up -d +``` + +## Solução de Problemas + +### Containers não iniciam + +Verifique os logs: +```bash +docker compose -f production.yml logs +``` + +### Erro de permissão no banco de dados + +Ajuste permissões do diretório de dados: +```bash +sudo chown -R 999:999 ../scms_data/markapi/data_prod +``` + +### Porta já em uso + +Edite o arquivo `production.yml` e altere as portas mapeadas. + +### Erro de memória + +Aumente a memória disponível para o Docker: +- **Linux**: Aumente a swap do sistema +- **Windows/macOS**: Ajuste nas configurações do Docker Desktop (Resources > Advanced) + +## Próximos Passos + +Após a instalação, consulte os seguintes guias: + +1. **[Guia de Validação de XML](./02-XML-Validation-Guide.md)** - Como validar documentos XML +2. **[Guia de Conversão para PDF](./03-XML-to-PDF-Conversion-Guide.md)** - Como converter XML para PDF +3. **[Configuração de Modelos DOCX](./04-DOCX-Layout-Configuration.md)** - Como personalizar layouts de PDF + +## Suporte + +Para questões ou problemas: + +- **Issues**: https://github.com/scieloorg/markapi/issues +- **Wiki**: https://github.com/scieloorg/markapi/wiki +- **Documentação Técnica**: Consulte o arquivo `README.md` no repositório + +## Referências + +- [Documentação do Docker](https://docs.docker.com/) +- [Docker Compose](https://docs.docker.com/compose/) +- [Django Deployment](https://docs.djangoproject.com/en/stable/howto/deployment/) diff --git a/docs/user-guide/02-XML-Validation-Guide.md b/docs/user-guide/02-XML-Validation-Guide.md new file mode 100644 index 0000000..6351a9c --- /dev/null +++ b/docs/user-guide/02-XML-Validation-Guide.md @@ -0,0 +1,353 @@ +# Guia de Validação de XML + +Este guia explica como utilizar o MarkAPI para validar documentos XML de acordo com os padrões SciELO. + +## O que é a Validação de XML? + +A validação de XML no MarkAPI verifica se seus documentos estão em conformidade com: + +1. **Estrutura XML**: Se o arquivo está bem-formado +2. **Schema SPS (SciELO Publishing Schema)**: Se segue o padrão de publicação SciELO +3. **Regras de Negócio**: Se atende aos requisitos específicos do SciELO +4. **Conteúdo**: Se os dados estão completos e corretos + +## Acessar o Sistema + +### 1. Fazer Login + +1. Acesse a URL do MarkAPI instalado (ex: `http://seu-servidor:8000`) +2. Clique em **"Login"** ou **"Entrar"** +3. Digite seu **usuário** e **senha** +4. Clique em **"Entrar"** + +Se você é administrador, também pode acessar o painel administrativo em `/django-admin/`. + +### 2. Navegação Inicial + +Após o login, você verá o painel principal com opções para: +- Enviar novos documentos XML +- Visualizar documentos já enviados +- Verificar status de validações e conversões + +## Como Validar um Documento XML + +### Método 1: Upload Através da Interface Web + +#### Passo 1: Acessar a Área de Upload + +1. No menu principal, clique em **"XML Documents"** ou **"Documentos XML"** +2. Clique no botão **"Add XML Document"** ou **"Adicionar Documento XML"** + +#### Passo 2: Selecionar o Arquivo + +1. Clique em **"Choose File"** ou **"Escolher Arquivo"** +2. Navegue até o arquivo XML em seu computador +3. Selecione o arquivo (formato `.xml`) +4. Clique em **"Open"** ou **"Abrir"** + +**Requisitos do Arquivo:** +- Formato: `.xml` +- Tamanho máximo: 10 MB (configurável) +- Codificação: UTF-8 recomendada +- Deve ser um XML válido de artigo científico no padrão SPS + +#### Passo 3: Enviar o Documento + +1. Revise as informações do arquivo +2. Clique em **"Upload"** ou **"Enviar"** +3. Aguarde a confirmação do upload + +#### Passo 4: Aguardar o Processamento + +Após o upload, o MarkAPI automaticamente: +1. Valida o arquivo XML +2. Gera um relatório de validação +3. Identifica erros e avisos +4. Opcionalmente, inicia a conversão para PDF/HTML (se configurado) + +O processamento é feito em segundo plano e pode levar alguns segundos a minutos, dependendo do tamanho do arquivo. + +### Método 2: Upload em Lote (Administradores) + +Para enviar múltiplos arquivos: + +1. Acesse o **painel administrativo** (`/django-admin/`) +2. Vá em **XML Manager** > **XML Documents** +3. Use a opção de importação em massa (se disponível) + +## Interpretar os Resultados da Validação + +### Acessar o Relatório de Validação + +1. Na lista de **"XML Documents"**, localize seu arquivo +2. Clique no nome do documento para ver os detalhes +3. Na página de detalhes, você verá: + - **Status do documento** + - **Data de upload** + - **Links para downloads** + +### Arquivos Gerados + +Após a validação, você terá acesso a: + +#### 1. Arquivo de Validação (CSV) + +**Localização**: Campo "Validation File" ou link "Download Validation Report" + +**Conteúdo**: Tabela com todos os resultados da validação + +**Colunas do CSV:** +- **line**: Número da linha no XML onde ocorreu o problema +- **message**: Descrição do erro ou aviso +- **level**: Nível de severidade (ERROR, WARNING, INFO) +- **type**: Tipo de validação (XML_STRUCTURE, SCHEMA, BUSINESS_RULE, CONTENT) +- **element**: Elemento XML onde ocorreu o problema + +**Exemplo:** +```csv +line,message,level,type,element +15,"Missing required element 'article-title'",ERROR,SCHEMA,title-group +23,"Invalid date format",WARNING,CONTENT,pub-date +45,"Author affiliation not found",WARNING,BUSINESS_RULE,contrib +``` + +#### 2. Arquivo de Exceções + +**Localização**: Campo "Exceptions File" ou link "Download Exceptions" + +**Conteúdo**: Detalhes técnicos de erros graves que impediram a validação completa + +### Níveis de Severidade + +#### ERROR (Erro) +- **Cor**: Vermelho +- **Significado**: Problema crítico que impede a publicação +- **Ação necessária**: Corrigir obrigatoriamente + +**Exemplos:** +- Estrutura XML mal-formada +- Elementos obrigatórios ausentes +- Valores inválidos em campos obrigatórios + +#### WARNING (Aviso) +- **Cor**: Amarelo/Laranja +- **Significado**: Problema que pode afetar a qualidade ou apresentação +- **Ação necessária**: Revisar e corrigir se possível + +**Exemplos:** +- Metadados incompletos +- Formatação inconsistente +- Referências sem DOI + +#### INFO (Informação) +- **Cor**: Azul +- **Significado**: Sugestão de melhoria ou informação relevante +- **Ação necessária**: Opcional + +**Exemplos:** +- Sugestões de otimização +- Informações sobre campos opcionais +- Estatísticas do documento + +## Corrigir Problemas e Revalidar + +### Passo 1: Baixar o Relatório de Validação + +1. Clique no link **"Download Validation Report"** +2. Abra o arquivo CSV em um editor de planilhas (Excel, LibreOffice Calc) +3. Ordene por nível de severidade (ERRORs primeiro) + +### Passo 2: Analisar os Erros + +Para cada erro: +1. Veja o número da **linha** no XML +2. Leia a **mensagem** de erro +3. Identifique o **elemento** afetado +4. Consulte a documentação SPS se necessário + +### Passo 3: Editar o Arquivo XML + +1. Abra o arquivo XML original em um editor de texto (VSCode, Notepad++, etc.) +2. Navegue até a linha indicada no relatório +3. Corrija o problema conforme a mensagem de erro +4. Salve o arquivo + +**Dica:** Use um editor XML com validação integrada para evitar erros de sintaxe. + +### Passo 4: Reenviar o Arquivo + +1. Volte ao MarkAPI +2. Faça upload do arquivo XML corrigido +3. Aguarde a nova validação +4. Compare os resultados com a validação anterior + +## Validação via API (Usuários Avançados) + +Para integração automática, o MarkAPI oferece uma API REST. + +### Autenticação + +```bash +# Obter token de autenticação +curl -X POST http://seu-servidor:8000/api/auth/login/ \ + -H "Content-Type: application/json" \ + -d '{"username": "seu-usuario", "password": "sua-senha"}' +``` + +### Enviar XML para Validação + +```bash +# Upload e validação +curl -X POST http://seu-servidor:8000/api/xml-documents/ \ + -H "Authorization: Token seu-token-aqui" \ + -F "xml_file=@/caminho/para/arquivo.xml" +``` + +### Verificar Status + +```bash +# Obter status do documento +curl -X GET http://seu-servidor:8000/api/xml-documents/{id}/ \ + -H "Authorization: Token seu-token-aqui" +``` + +### Baixar Relatório + +```bash +# Download do relatório de validação +curl -X GET http://seu-servidor:8000/api/xml-documents/{id}/validation-report/ \ + -H "Authorization: Token seu-token-aqui" \ + -o validation-report.csv +``` + +## Problemas Comuns e Soluções + +### Erro: "XML mal-formado" + +**Causa**: Sintaxe XML inválida + +**Solução**: +1. Verifique se todas as tags estão fechadas corretamente +2. Verifique caracteres especiais (use entidades XML como `<`, `>`, `&`) +3. Valide a codificação do arquivo (deve ser UTF-8) +4. Use um validador XML online para identificar o problema + +### Erro: "Elemento obrigatório ausente" + +**Causa**: O XML não contém todos os elementos requeridos pelo padrão SPS + +**Solução**: +1. Consulte a mensagem de erro para identificar qual elemento está faltando +2. Adicione o elemento no local correto do XML +3. Consulte a documentação SPS: https://docs.scielo.org/ + +### Erro: "Schema validation failed" + +**Causa**: O XML não está em conformidade com o schema SPS + +**Solução**: +1. Verifique se está usando a versão correta do SPS +2. Revise a estrutura do documento +3. Compare com exemplos de XML válidos +4. Consulte a documentação: https://docs.scielo.org/ + +### Aviso: "Referências incompletas" + +**Causa**: Referências bibliográficas sem informações completas + +**Solução**: +1. Complete os metadados das referências (autores, título, ano, etc.) +2. Adicione DOI quando disponível +3. Verifique a formatação das citações + +### Upload falha ou trava + +**Causa**: Arquivo muito grande ou problema de rede + +**Solução**: +1. Verifique o tamanho do arquivo (máximo configurado) +2. Verifique sua conexão de internet +3. Tente novamente em alguns minutos +4. Contate o administrador se o problema persistir + +## Boas Práticas + +### Antes de Validar + +1. **Verifique o arquivo localmente**: Use um editor XML com validação +2. **Garanta a codificação UTF-8**: Evite problemas com caracteres especiais +3. **Organize seus arquivos**: Use nomes descritivos (ex: `artigo-v01.xml`, `artigo-v02.xml`) +4. **Mantenha backups**: Guarde cópias dos arquivos originais + +### Durante a Validação + +1. **Documente as correções**: Mantenha um registro das alterações feitas +2. **Valide incrementalmente**: Corrija erros e valide novamente +3. **Priorize ERRORs**: Corrija erros críticos antes dos avisos +4. **Teste diferentes cenários**: Valide com diferentes tipos de conteúdo + +### Depois da Validação + +1. **Revise o relatório completo**: Não ignore avisos +2. **Mantenha registros**: Guarde os relatórios de validação +3. **Documente problemas recorrentes**: Ajude a melhorar o processo +4. **Compartilhe conhecimento**: Ajude outros usuários com problemas similares + +## Recursos Adicionais + +### Documentação Técnica + +- **SPS (SciELO Publishing Schema)**: https://docs.scielo.org/ +- **PMC/JATS**: https://jats.nlm.nih.gov/ +- **Packtools**: https://github.com/scieloorg/packtools + +### Ferramentas Auxiliares + +- **XML Validators Online**: https://www.xmlvalidation.com/ +- **Visual Studio Code**: Editor com extensões XML +- **Oxygen XML Editor**: Editor XML profissional +- **LibreOffice Calc**: Para visualizar relatórios CSV + +### Exemplos de XML + +Consulte o repositório de exemplos: +- https://github.com/scieloorg/scielo_publishing_schema +- Procure por arquivos de exemplo na pasta `tests/fixtures/` + +## Suporte + +Se você encontrar problemas ou tiver dúvidas: + +1. **Consulte a documentação**: https://github.com/scieloorg/markapi/wiki +2. **Abra um issue**: https://github.com/scieloorg/markapi/issues +3. **Contate o suporte**: Através dos canais oficiais SciELO + +## Fluxo de Trabalho Recomendado + +``` +1. Preparar arquivo XML + ↓ +2. Fazer upload no MarkAPI + ↓ +3. Aguardar validação automática + ↓ +4. Baixar relatório de validação + ↓ +5. Analisar erros e avisos + ↓ +6. Corrigir problemas no XML + ↓ +7. Reenviar arquivo corrigido + ↓ +8. Repetir até validação bem-sucedida + ↓ +9. Proceder com conversão para PDF/HTML +``` + +## Próximos Passos + +Após validar seu XML com sucesso: + +- **[Converter XML para PDF](./03-XML-to-PDF-Conversion-Guide.md)**: Gere PDFs do seu artigo +- **[Converter XML para HTML](./04-XML-to-HTML-Conversion-Guide.md)**: Gere visualização web +- **[Personalizar Layouts](./05-DOCX-Layout-Configuration.md)**: Customize a aparência dos PDFs diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md new file mode 100644 index 0000000..58f0f4b --- /dev/null +++ b/docs/user-guide/README.md @@ -0,0 +1,217 @@ +# Documentação do MarkAPI para Usuários Finais + +Bem-vindo à documentação do MarkAPI! Este conjunto de guias foi criado para ajudar usuários finais (não desenvolvedores) a instalar, configurar e utilizar o MarkAPI para validar e converter documentos XML no padrão SciELO. + +## Sobre o MarkAPI + +O MarkAPI é uma aplicação web projetada para: + +- **Validar** documentos XML de acordo com o padrão SciELO Publishing Schema (SPS) +- **Converter** XML para diferentes formatos (PDF, HTML, DOCX) +- **Processar** documentos em lote +- **Gerar relatórios** detalhados de validação + +## Documentação Disponível + +### Para Começar + +#### 📘 [Guia de Instalação](./01-Installation-Guide.md) +Instruções completas para instalar o MarkAPI em seu servidor usando Docker. + +**Inclui:** +- Pré-requisitos e instalação do Docker +- Passo a passo da instalação +- Configuração de variáveis de ambiente +- Solução de problemas comuns +- Comandos úteis para gerenciar a aplicação + +**Público:** Administradores de sistema, usuários com conhecimento básico de terminal + +--- + +### Usando o MarkAPI + +#### ✅ [Guia de Validação de XML](./02-XML-Validation-Guide.md) +Como validar documentos XML usando o MarkAPI. + +**Inclui:** +- Como fazer upload de arquivos XML +- Interpretar relatórios de validação +- Compreender níveis de severidade (ERROR, WARNING, INFO) +- Corrigir problemas e revalidar +- Boas práticas de validação +- Uso da API para validação automatizada + +**Público:** Editores, revisores, usuários que trabalham com XML + +--- + +### Guias Adicionais (Em Desenvolvimento) + +Os seguintes guias estão planejados ou em desenvolvimento: + +- **Guia de Conversão XML para PDF**: Como gerar PDFs a partir de arquivos XML +- **Guia de Conversão XML para HTML**: Como gerar versões web dos artigos +- **Configuração de Modelos DOCX**: Como personalizar o layout dos PDFs gerados +- **Processamento em Lote**: Como processar múltiplos arquivos simultaneamente + +## Recursos Rápidos + +### Links Úteis + +- **Repositório GitHub**: https://github.com/scieloorg/markapi +- **Wiki do Projeto**: https://github.com/scieloorg/markapi/wiki +- **Issues e Suporte**: https://github.com/scieloorg/markapi/issues +- **Documentação SPS**: https://docs.scielo.org/ + +### Acesso Rápido + +Após a instalação, você pode acessar: + +- **Aplicação Web**: `http://seu-servidor:8000` +- **Painel Admin**: `http://seu-servidor:8000/django-admin/` +- **API**: `http://seu-servidor:8000/api/` +- **Documentação da API**: `http://seu-servidor:8000/api/docs/` + +## Fluxo de Trabalho Típico + +```mermaid +graph TD + A[Instalar MarkAPI] --> B[Fazer Login] + B --> C[Upload de Arquivo XML] + C --> D[Validação Automática] + D --> E{Validação OK?} + E -->|Não| F[Baixar Relatório] + F --> G[Corrigir Erros] + G --> C + E -->|Sim| H[Converter para PDF/HTML] + H --> I[Baixar Arquivos Gerados] +``` + +## Para Diferentes Tipos de Usuários + +### 👨‍💼 Editores e Coordenadores + +**Você deve ler:** +1. Visão geral deste README +2. Como fazer upload e validar XML (seções básicas do Guia de Validação) +3. Como interpretar relatórios de validação + +**Você não precisa:** +- Instalar o MarkAPI (peça ao administrador de TI) +- Conhecer detalhes técnicos de Docker ou linha de comando + +### 👨‍💻 Administradores de Sistema + +**Você deve ler:** +1. Guia de Instalação completo +2. Seções de configuração e manutenção +3. Comandos úteis e solução de problemas + +**Recursos adicionais:** +- README.md na raiz do projeto (documentação técnica) +- Documentação do Docker Compose +- Logs do sistema + +### 📝 Autores e Revisores de Conteúdo + +**Você deve ler:** +1. Como fazer upload de XML +2. Como interpretar erros de validação +3. Boas práticas de preparação de XML + +**Foco em:** +- Qualidade do conteúdo XML +- Correção de erros de metadados +- Conformidade com padrões SciELO + +## Perguntas Frequentes (FAQ) + +### Instalação e Configuração + +**Q: Preciso saber programar para usar o MarkAPI?** +R: Não. Para usar a interface web, basta saber navegar em um site. Para instalar, é necessário conhecimento básico de terminal e Docker. + +**Q: Posso instalar no Windows?** +R: Sim, usando Docker Desktop. Siga as instruções no Guia de Instalação. + +**Q: Quanto tempo leva a instalação?** +R: Entre 30 minutos a 1 hora, dependendo da velocidade da internet e do computador. + +**Q: Preciso de um servidor dedicado?** +R: Não necessariamente. Pode usar seu próprio computador para testes, mas para produção recomenda-se um servidor. + +### Uso e Validação + +**Q: Que tipos de arquivo posso validar?** +R: Arquivos XML no padrão SciELO Publishing Schema (SPS), baseado em JATS. + +**Q: Há limite de tamanho para os arquivos?** +R: Por padrão, 10 MB. O administrador pode ajustar esse limite. + +**Q: Quanto tempo leva a validação?** +R: Geralmente de alguns segundos a 2-3 minutos, dependendo do tamanho e complexidade do XML. + +**Q: Os erros de validação impedem a conversão para PDF?** +R: Erros críticos (ERROR) podem impedir. Avisos (WARNING) geralmente não impedem, mas devem ser revisados. + +### Solução de Problemas + +**Q: O que fazer se o upload falhar?** +R: Verifique o tamanho do arquivo, sua conexão de internet e tente novamente. Se persistir, contate o administrador. + +**Q: Como reportar um bug?** +R: Abra um issue no GitHub: https://github.com/scieloorg/markapi/issues + +**Q: Onde encontro exemplos de XML válidos?** +R: No repositório SPS: https://github.com/scieloorg/scielo_publishing_schema + +## Suporte e Comunidade + +### Obter Ajuda + +1. **Documentação**: Comece sempre consultando os guias +2. **Wiki**: Verifique a wiki para tutoriais e dicas: https://github.com/scieloorg/markapi/wiki +3. **Issues**: Pesquise issues existentes ou abra um novo: https://github.com/scieloorg/markapi/issues +4. **Contato Direto**: Entre em contato com a equipe SciELO através dos canais oficiais + +### Contribuir + +Você pode contribuir: +- Reportando bugs e problemas +- Sugerindo melhorias +- Compartilhando casos de uso +- Ajudando outros usuários +- Melhorando a documentação + +## Licença e Créditos + +**MarkAPI** é um projeto open-source desenvolvido por SciELO. + +- **Licença**: GPLv3 +- **Copyright**: SciELO +- **Repositório**: https://github.com/scieloorg/markapi + +## Histórico de Atualizações + +### Versão 1.0 (2025) +- Documentação inicial para usuários finais +- Guia de Instalação +- Guia de Validação de XML +- README da documentação do usuário + +--- + +## Próximos Passos + +Escolha o guia apropriado de acordo com sua necessidade: + +1. **Novo no MarkAPI?** → Comece com o [Guia de Instalação](./01-Installation-Guide.md) +2. **Já instalado?** → Vá para o [Guia de Validação](./02-XML-Validation-Guide.md) +3. **Precisa de ajuda?** → Consulte a seção de Suporte acima + +--- + +**Última atualização**: Outubro 2025 +**Versão da documentação**: 1.0 +**Compatível com MarkAPI**: 1.x From ac566a4e5a7dd7294d5a96870abcd37f31670db9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 14 Oct 2025 17:09:59 +0000 Subject: [PATCH 3/3] Update installation guide and add Wiki content summary Co-authored-by: robertatakenaka <505143+robertatakenaka@users.noreply.github.com> --- docs/user-guide/01-Installation-Guide.md | 31 +++- docs/user-guide/Wiki-Content-Summary.md | 210 +++++++++++++++++++++++ 2 files changed, 240 insertions(+), 1 deletion(-) create mode 100644 docs/user-guide/Wiki-Content-Summary.md diff --git a/docs/user-guide/01-Installation-Guide.md b/docs/user-guide/01-Installation-Guide.md index 5f16c2a..982de71 100644 --- a/docs/user-guide/01-Installation-Guide.md +++ b/docs/user-guide/01-Installation-Guide.md @@ -98,15 +98,27 @@ chmod 700 ../scms_data/markapi/data_prod ### Passo 4: Construir as Imagens Docker +**Nota:** O MarkAPI suporta duas formas de implantação em produção: +1. **Docker Compose** (recomendado para servidores únicos) - usando `production.yml` +2. **Kubernetes** (recomendado para clusters) - veja os arquivos em `kubernetes/hml/` + +Para Docker Compose, se o arquivo `production.yml` não existir, você pode criar um baseado no `local.yml` ou usar diretamente o `local.yml` com ajustes nas variáveis de ambiente. + ```bash # Construir as imagens do MarkAPI +# Se production.yml existir: docker compose -f production.yml build + +# Alternativamente, use local.yml para testes ou ambientes menores: +# docker compose -f local.yml build ``` Este processo pode levar alguns minutos na primeira execução. ### Passo 5: Inicializar o Banco de Dados +**Nota:** Substitua `production.yml` por `local.yml` se estiver usando este arquivo. + ```bash # Executar migrações do banco de dados docker compose -f production.yml run --rm django python manage.py migrate @@ -161,13 +173,30 @@ Após a instalação bem-sucedida: Faça login com as credenciais do superusuário criadas no Passo 5. +## Implantação com Kubernetes (Alternativa) + +Para ambientes de produção em larga escala, o MarkAPI pode ser implantado usando Kubernetes: + +```bash +# Aplicar configurações do Kubernetes +kubectl apply -f kubernetes/hml/ + +# Verificar os pods +kubectl get pods + +# Verificar os serviços +kubectl get services +``` + +Consulte os arquivos YAML em `kubernetes/hml/` para mais detalhes sobre a configuração. + ## Configuração Opcional: Proxy Reverso (Nginx/Traefik) Para ambiente de produção, é recomendado configurar um proxy reverso com HTTPS. ### Usando Traefik (incluído) -O MarkAPI já vem configurado com Traefik. Edite o arquivo `.envs/.production/.django` e configure: +O MarkAPI já vem configurado com Traefik para implantações Docker Compose. Edite o arquivo `.envs/.production/.django` e configure: ``` DJANGO_ALLOWED_HOSTS=seu-dominio.com diff --git a/docs/user-guide/Wiki-Content-Summary.md b/docs/user-guide/Wiki-Content-Summary.md new file mode 100644 index 0000000..8dac6ce --- /dev/null +++ b/docs/user-guide/Wiki-Content-Summary.md @@ -0,0 +1,210 @@ +# Conteúdo para Wiki do MarkAPI + +Este documento contém um resumo do conteúdo da documentação do usuário que pode ser usado para popular as páginas da Wiki do MarkAPI em: https://github.com/scieloorg/markapi/wiki + +## Estrutura Sugerida para a Wiki + +A documentação do usuário foi criada e está disponível na pasta `docs/user-guide/` do repositório. Recomendamos criar as seguintes páginas na Wiki: + +### 1. Home (Página Principal) + +Use o conteúdo de: `docs/user-guide/README.md` + +**URL sugerida:** https://github.com/scieloorg/markapi/wiki + +**Resumo:** +- Visão geral do MarkAPI +- Links para todos os guias +- Fluxo de trabalho típico +- FAQ básico +- Recursos rápidos + +--- + +### 2. Guia de Instalação + +Use o conteúdo de: `docs/user-guide/01-Installation-Guide.md` + +**URL sugerida:** https://github.com/scieloorg/markapi/wiki/Guia-de-Instalacao + +**Conteúdo:** +- Pré-requisitos (Docker, hardware) +- Instalação do Docker (Linux, Windows, macOS) +- Passo a passo da instalação do MarkAPI +- Configuração de variáveis de ambiente +- Inicialização e verificação +- Comandos úteis +- Solução de problemas +- Atualização da aplicação +- Backup e restauração + +**Análogo a:** https://github.com/scieloorg/opac_5/wiki/Upload-application-installation (mas adaptado para usuários não-desenvolvedores) + +--- + +### 3. Guia de Validação de XML + +Use o conteúdo de: `docs/user-guide/02-XML-Validation-Guide.md` + +**URL sugerida:** https://github.com/scieloorg/markapi/wiki/Validacao-de-XML + +**Conteúdo:** +- O que é validação de XML +- Como fazer login e acessar o sistema +- Como fazer upload de arquivos XML +- Como interpretar relatórios de validação +- Níveis de severidade (ERROR, WARNING, INFO) +- Como corrigir problemas e revalidar +- Uso da API para validação automatizada +- Problemas comuns e soluções +- Boas práticas +- Fluxo de trabalho recomendado + +**Análogo a:** https://github.com/scieloorg/markapi/wiki/Converter-XML-para-PDF (mas focado em validação) + +--- + +## Como Popular a Wiki + +### Opção 1: Copiar e Colar (Simples) + +1. Acesse https://github.com/scieloorg/markapi/wiki +2. Clique em "New Page" para cada guia +3. Copie o conteúdo dos arquivos `.md` correspondentes +4. Cole no editor da Wiki +5. Ajuste formatação se necessário +6. Salve a página + +### Opção 2: Clonar o Wiki (Avançado) + +```bash +# Clonar o repositório da Wiki +git clone https://github.com/scieloorg/markapi.wiki.git + +# Copiar os arquivos de documentação +cp docs/user-guide/README.md markapi.wiki/Home.md +cp docs/user-guide/01-Installation-Guide.md markapi.wiki/Guia-de-Instalacao.md +cp docs/user-guide/02-XML-Validation-Guide.md markapi.wiki/Validacao-de-XML.md + +# Commit e push +cd markapi.wiki +git add . +git commit -m "Adicionar documentação do usuário" +git push origin master +``` + +## Mapeamento de Páginas + +| Arquivo no Repositório | Página na Wiki | URL | +|------------------------|----------------|-----| +| `docs/user-guide/README.md` | Home | `/wiki` | +| `docs/user-guide/01-Installation-Guide.md` | Guia de Instalação | `/wiki/Guia-de-Instalacao` | +| `docs/user-guide/02-XML-Validation-Guide.md` | Validação de XML | `/wiki/Validacao-de-XML` | + +## Links Internos a Ajustar + +Quando copiar o conteúdo para a Wiki, ajuste os links relativos para links da Wiki: + +**De:** +```markdown +[Guia de Instalação](./01-Installation-Guide.md) +``` + +**Para:** +```markdown +[Guia de Instalação](Guia-de-Instalacao) +``` + +## Páginas Existentes na Wiki + +Mantenha as páginas existentes e adicione links para a nova documentação: + +- **Guia rápido: baixar e configurar o modelo do MarkAPI para marcação de referências em PDF** + - URL: https://github.com/scieloorg/markapi/wiki/Guia-r%C3%A1pido:-baixar-e-configurar-o-modelo-do-MarkAPI-para-marca%C3%A7%C3%A3o-de-refer%C3%AAncias-em-PDF + - Ação: Adicionar link para o novo Guia de Instalação + - Relação: Complementar - este guia específico pode ser linkado na seção de configuração avançada + +## Navegação Sugerida na Wiki + +Adicione uma barra lateral (Sidebar) com navegação: + +```markdown +## Documentação do Usuário + +### Começando +- [Home](Home) +- [Guia de Instalação](Guia-de-Instalacao) + +### Usando o MarkAPI +- [Validação de XML](Validacao-de-XML) + +### Avançado +- [Configuração de Modelo PDF](Guia-rápido:-baixar-e-configurar-o-modelo-do-MarkAPI-para-marcação-de-referências-em-PDF) + +### Recursos +- [Repositório](https://github.com/scieloorg/markapi) +- [Issues](https://github.com/scieloorg/markapi/issues) +- [Documentação SPS](https://docs.scielo.org/) +``` + +## Checklist de Publicação + +- [ ] Criar página Home na Wiki +- [ ] Criar página Guia de Instalação +- [ ] Criar página Validação de XML +- [ ] Ajustar links internos +- [ ] Adicionar barra lateral de navegação +- [ ] Adicionar links nas páginas existentes +- [ ] Revisar formatação +- [ ] Testar todos os links +- [ ] Anunciar nova documentação + +## Manutenção Futura + +Os arquivos de documentação estão no repositório em `docs/user-guide/`. Quando atualizar: + +1. Edite os arquivos `.md` no repositório +2. Faça commit e push das alterações +3. Copie o conteúdo atualizado para a Wiki +4. Mantenha sincronia entre repositório e Wiki + +**Vantagens:** +- Documentação versionada com o código +- Facilita revisões via Pull Requests +- Permite que desenvolvedores contribuam com a documentação + +## Tarefas Completadas + +✅ Criada documentação de instalação (análogo ao Upload application installation) +✅ Criada documentação de validação de XML (análogo ao Converter XML para PDF) +✅ Documentação em português e adaptada para usuários não-desenvolvedores +✅ Incluídas instruções para Windows, macOS e Linux +✅ Adicionadas seções de solução de problemas +✅ Incluídos exemplos práticos e comandos +✅ Criado índice geral da documentação +✅ Atualizado README principal com links para documentação + +## Próximos Passos Recomendados + +Para completar ainda mais a documentação: + +1. **Guia de Conversão XML para PDF** - Instruções detalhadas sobre conversão +2. **Guia de Conversão XML para HTML** - Como gerar versões web +3. **Configuração Avançada** - Personalização de layouts DOCX +4. **Processamento em Lote** - Como processar múltiplos arquivos +5. **Screenshots/Vídeos** - Adicionar capturas de tela da interface +6. **Tutoriais em Vídeo** - Criar vídeos dos processos principais + +## Feedback + +Se tiver sugestões para melhorar esta documentação: + +1. Abra um issue: https://github.com/scieloorg/markapi/issues +2. Envie um Pull Request com melhorias +3. Entre em contato com a equipe SciELO + +--- + +**Preparado por:** Copilot Agent +**Data:** Outubro 2025 +**Versão:** 1.0