From 78672a2175e6bed644e97a87a0cd9771aa7a87ce Mon Sep 17 00:00:00 2001 From: GitInno <86991526+gitnnolabs@users.noreply.github.com> Date: Fri, 15 May 2026 14:40:06 -0300 Subject: [PATCH] Update the README.md of the project. --- README.md | 213 +++++++++++++++++++++--------------------------------- 1 file changed, 84 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index 725b37e..9357118 100644 --- a/README.md +++ b/README.md @@ -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 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/`