Skip to content

Reescreve README com objetivo RCT, testes e parâmetros de configuração #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gitnnolabs merged 1 commit into from
May 15, 2026
Merged

Reescreve README com objetivo RCT, testes e parâmetros de configuração #90

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 84 additions & 129 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,184 +1,139 @@
# MarkAPI

MarkAPI is a project designed to tag, validate, and convert XML documents in the SciELO publishing context. It offers tools for:

- Tagging XML structure and content
- Validating XML against defined schemas, business rules and content
- Converting XML to HTML, DOCX, and PDF
# MarkAPI — SciELO Research Communication Tools (RCT)

[![Black code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)

License: GPLv3
Repositório: [scieloorg/markapi](https://github.com/scieloorg/markapi) · Licença: GPLv3

Documentação completa em texto: **[README.txt](README.txt)**

---

## Development Environment
## Objetivo do projeto

You can use Docker directly or via `make`. To see available commands:
Plataforma para produção, avaliação e rastreio de objetos de comunicação de pesquisa (manuscritos, preprints, artigos, dados, livros, capítulos), com **XML SPS** como registro único e rastreável.

```bash
make help
```
| Área | Descrição |
|------|-----------|
| Marcação | Pipeline DOCX/LaTeX/ODT → XML SPS com LLM; revisão humana sempre possível |
| Validação | Schemas, regras de negócio e packtools |
| Avaliação | Checklists (CONSORT, PRISMA, STROBE, ARRIVE) e critérios FAIR no XML |
| Saídas | Pacote SPS, PDF, HTML, XML Crossref/PubMed/PMC, JSON DOAJ |
| Integração | API REST (JWT); Wagtail embutido; SciELO Core e publicação via Upload/OPAC |

Example output:
**Stack:** Python 3.12, Django 6, Wagtail 7.4, DRF, Celery, Redis, PostgreSQL, packtools.

```bash
Usage: make [target] [argument] ...

Argument:
compose = {compose_file_name}

Targets:
help Show this help
app_version Show app version
vcs_ref Show last commit ref
build_date Show build date
build Build app using $(COMPOSE_FILE_DEV)
up Start app using $(COMPOSE_FILE_DEV)
logs Show logs using $(COMPOSE_FILE_DEV)
stop Stop app using $(COMPOSE_FILE_DEV)
ps Show containers using $(COMPOSE_FILE_DEV)
rm Remove containers using $(COMPOSE_FILE_DEV)
django_shell Open Django shell
wagtail_sync Sync Wagtail page fields
wagtail_update_translation_field Update Wagtail translation fields
django_createsuperuser Create Django superuser
django_bash Bash into Django container
django_test Run Django tests
django_fast Run fast Django tests
django_makemigrations Make migrations
django_migrate Apply migrations
django_makemessages Run makemessages
django_compilemessages Run compilemessages
django_dump_auth Dump Django auth data
django_load_auth Load Django auth data
dump_data Dump database to .sql
restore_data Restore database from .sql
```
**Princípios:** IA auxilia, humano revisa; integração aditiva a sistemas editoriais existentes; LLM preferencialmente on-premise.

### Common Commands
---

Build the development environment:
## Desenvolvimento

```bash
make build compose=local.yml
# or simply
make
```
**Pré-requisitos:** Docker, Docker Compose, Make.

Start the project:
| Serviço | URL local |
|---------|-----------|
| Wagtail/Django | http://127.0.0.1:8009 |
| MailHog | http://127.0.0.1:8029 |
| PostgreSQL | `localhost:5439` |
| Redis | `localhost:6399` |

```bash
make build
make up
make django_migrate
make django_createsuperuser
```

Stop the project:

```bash
make stop
make help # todos os alvos Make
```

To use a custom `.yml` or environment, copy `.envs` and `compose` folders, then run:
Compose: `local.yml` (dev). Ambiente em `.envs/.local/`. Volume Postgres: `../scms_data/markapi/data_dev`.

```bash
make <target> compose=your_config.yml
```

The stack uses two Docker Compose files:

* `local.yml` (development)
* `production.yml` (production)
**Modelo LLM:** [wiki — baixar e configurar modelo](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)

---

## Settings

Refer to the [settings documentation](http://cookiecutter-django.readthedocs.io/en/latest/settings.html).

---
## Testes

## Usage Guide

### User Setup

* **Normal user:** Sign up via UI. Confirm email using the console output.
* **Superuser:** Run:
Settings: `config.settings.test` · Guia: **[docs/testing.md](docs/testing.md)**

```bash
python manage.py createsuperuser
```

Use different browsers to test both user types simultaneously.

---

### Type Checks

```bash
mypy core
make build
make up
make django_migrate
make django_test # manage.py test
make django_fast
make pytest
make pytest_fast
make pytest_cov
```

---

### Testing

Run tests and generate coverage report:

```bash
coverage run -m pytest
coverage html
open htmlcov/index.html
docker compose -f local.yml run --rm django python manage.py test --settings=config.settings.test
docker compose -f local.yml run --rm django pytest
```

Or just:

```bash
pytest
```
CI: job `tests` em `.github/workflows/ci.yml` (`manage.py test` + `pytest`, sem ignorar falhas).

---

### Live Reload & Sass
## Configuração

See: [Live reloading & SASS](https://cookiecutter-django.readthedocs.io/en/latest/developing-locally.html#sass-compilation-live-reloading)
### Módulos Django

---
| `DJANGO_SETTINGS_MODULE` | Uso |
|--------------------------|-----|
| `config.settings.local` | Desenvolvimento (defeito do `manage.py`) |
| `config.settings.production` | Produção |
| `config.settings.test` | Testes (`make django_test`, `pytest`) |

### Celery
### Ficheiros de ambiente

To start a worker:
- `.envs/.local/.django` — `USE_DOCKER`, `REDIS_URL`, `HF_TOKEN`, `FETCH_DATA_TIMEOUT`, Flower
- `.envs/.local/.postgres` — `POSTGRES_*`
- `.envs/.production/.django` — `DJANGO_SECRET_KEY`, `DJANGO_ALLOWED_HOSTS`, `SENTRY_DSN`, …

```bash
cd core
celery -A config.celery_app worker -l info
```
No container, o entrypoint define `DATABASE_URL` e `CELERY_BROKER_URL` a partir de `POSTGRES_*` e `REDIS_URL`.

Ensure you're in the correct directory (`core`) for Celery to work properly.
### Variáveis principais

---
| Variável | Descrição |
|----------|-----------|
| `DATABASE_URL` | PostgreSQL (montada no entrypoint) |
| `POSTGRES_HOST` / `POSTGRES_PORT` / `POSTGRES_DB` | Credenciais e base |
| `REDIS_URL` | Redis (ex.: `redis://redis:6379/0`) |
| `CELERY_BROKER_URL` | Broker Celery (= `REDIS_URL` no entrypoint) |
| `DJANGO_SECRET_KEY` | Chave secreta (produção) |
| `DJANGO_ALLOWED_HOSTS` | Hosts permitidos |
| `DJANGO_CSRF_TRUSTED_ORIGINS` | Origens CSRF |
| `LLAMA_ENABLED` | Ativar LLM local (`false` em testes) |
| `HF_TOKEN` | Token Hugging Face (download do modelo) |
| `CORE_API_DOMAIN` | API SciELO Core (defeito `https://core.scielo.org`) |
| `DRF_PAGE_SIZE` | Paginação da API REST |
| `SENTRY_DSN` | Monitorização (produção) |
| `COMPRESS_ENABLED` | Compressor de estáticos (produção) |

### Email (MailHog)
Lista completa e notas: **[README.txt](README.txt)** (secção 4).

A local SMTP server with web UI is included.
### Requisitos Python

Access at: `http://127.0.0.1:8025`
- `requirements/base.txt` — runtime
- `requirements/local.txt` — dev + pytest
- `requirements/production.txt` — produção

See [Docker deployment docs](http://cookiecutter-django.readthedocs.io/en/latest/deployment-with-docker.html) for details.
Após alterar dependências: `make build`.

---

### Sentry

Sentry is pre-configured for logging. Set the DSN URL in production.
## Outros

Signup at: [https://sentry.io/signup/?code=cookiecutter](https://sentry.io/signup/?code=cookiecutter)

---

## Deployment
```bash
mypy core # verificação de tipos (não é suite de testes)
```

See full [Docker deployment guide](http://cookiecutter-django.readthedocs.io/en/latest/deployment-with-docker.html).
**Celery:** serviços `celeryworker` e `celerybeat` no `local.yml`.

## Download Model
**Deploy:** ver `production.yml` e documentação Docker do projeto.

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
**Docs:** `docs/testing.md`, `docs/pr/`
Loading