Skip to content

Commit 78672a2

Browse files
gitnnolabsgitnnolabs
committed
Update the README.md of the project.
1 parent 1359be4 commit 78672a2

1 file changed

Lines changed: 84 additions & 129 deletions

File tree

‎README.md‎

Lines changed: 84 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -1,184 +1,139 @@
1-
# MarkAPI
2-
3-
MarkAPI is a project designed to tag, validate, and convert XML documents in the SciELO publishing context. It offers tools for:
4-
5-
- Tagging XML structure and content
6-
- Validating XML against defined schemas, business rules and content
7-
- Converting XML to HTML, DOCX, and PDF
1+
# MarkAPI — SciELO Research Communication Tools (RCT)
82

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

11-
License: GPLv3
5+
Repositório: [scieloorg/markapi](https://github.com/scieloorg/markapi) · Licença: GPLv3
6+
7+
Documentação completa em texto: **[README.txt](README.txt)**
128

139
---
1410

15-
## Development Environment
11+
## Objetivo do projeto
1612

17-
You can use Docker directly or via `make`. To see available commands:
13+
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.
1814

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

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

25-
```bash
26-
Usage: make [target] [argument] ...
27-
28-
Argument:
29-
compose = {compose_file_name}
30-
31-
Targets:
32-
help Show this help
33-
app_version Show app version
34-
vcs_ref Show last commit ref
35-
build_date Show build date
36-
build Build app using $(COMPOSE_FILE_DEV)
37-
up Start app using $(COMPOSE_FILE_DEV)
38-
logs Show logs using $(COMPOSE_FILE_DEV)
39-
stop Stop app using $(COMPOSE_FILE_DEV)
40-
ps Show containers using $(COMPOSE_FILE_DEV)
41-
rm Remove containers using $(COMPOSE_FILE_DEV)
42-
django_shell Open Django shell
43-
wagtail_sync Sync Wagtail page fields
44-
wagtail_update_translation_field Update Wagtail translation fields
45-
django_createsuperuser Create Django superuser
46-
django_bash Bash into Django container
47-
django_test Run Django tests
48-
django_fast Run fast Django tests
49-
django_makemigrations Make migrations
50-
django_migrate Apply migrations
51-
django_makemessages Run makemessages
52-
django_compilemessages Run compilemessages
53-
django_dump_auth Dump Django auth data
54-
django_load_auth Load Django auth data
55-
dump_data Dump database to .sql
56-
restore_data Restore database from .sql
57-
```
25+
**Princípios:** IA auxilia, humano revisa; integração aditiva a sistemas editoriais existentes; LLM preferencialmente on-premise.
5826

59-
### Common Commands
27+
---
6028

61-
Build the development environment:
29+
## Desenvolvimento
6230

63-
```bash
64-
make build compose=local.yml
65-
# or simply
66-
make
67-
```
31+
**Pré-requisitos:** Docker, Docker Compose, Make.
6832

69-
Start the project:
33+
| Serviço | URL local |
34+
|---------|-----------|
35+
| Wagtail/Django | http://127.0.0.1:8009 |
36+
| MailHog | http://127.0.0.1:8029 |
37+
| PostgreSQL | `localhost:5439` |
38+
| Redis | `localhost:6399` |
7039

7140
```bash
41+
make build
7242
make up
43+
make django_migrate
44+
make django_createsuperuser
7345
```
7446

75-
Stop the project:
76-
7747
```bash
78-
make stop
48+
make help # todos os alvos Make
7949
```
8050

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

83-
```bash
84-
make <target> compose=your_config.yml
85-
```
86-
87-
The stack uses two Docker Compose files:
88-
89-
* `local.yml` (development)
90-
* `production.yml` (production)
53+
**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)
9154

9255
---
9356

94-
## Settings
95-
96-
Refer to the [settings documentation](http://cookiecutter-django.readthedocs.io/en/latest/settings.html).
97-
98-
---
57+
## Testes
9958

100-
## Usage Guide
101-
102-
### User Setup
103-
104-
* **Normal user:** Sign up via UI. Confirm email using the console output.
105-
* **Superuser:** Run:
59+
Settings: `config.settings.test` · Guia: **[docs/testing.md](docs/testing.md)**
10660

10761
```bash
108-
python manage.py createsuperuser
109-
```
110-
111-
Use different browsers to test both user types simultaneously.
112-
113-
---
114-
115-
### Type Checks
116-
117-
```bash
118-
mypy core
62+
make build
63+
make up
64+
make django_migrate
65+
make django_test # manage.py test
66+
make django_fast
67+
make pytest
68+
make pytest_fast
69+
make pytest_cov
11970
```
12071

121-
---
122-
123-
### Testing
124-
125-
Run tests and generate coverage report:
126-
12772
```bash
128-
coverage run -m pytest
129-
coverage html
130-
open htmlcov/index.html
73+
docker compose -f local.yml run --rm django python manage.py test --settings=config.settings.test
74+
docker compose -f local.yml run --rm django pytest
13175
```
13276

133-
Or just:
134-
135-
```bash
136-
pytest
137-
```
77+
CI: job `tests` em `.github/workflows/ci.yml` (`manage.py test` + `pytest`, sem ignorar falhas).
13878

13979
---
14080

141-
### Live Reload & Sass
81+
## Configuração
14282

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

145-
---
85+
| `DJANGO_SETTINGS_MODULE` | Uso |
86+
|--------------------------|-----|
87+
| `config.settings.local` | Desenvolvimento (defeito do `manage.py`) |
88+
| `config.settings.production` | Produção |
89+
| `config.settings.test` | Testes (`make django_test`, `pytest`) |
14690

147-
### Celery
91+
### Ficheiros de ambiente
14892

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

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

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

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

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

162-
A local SMTP server with web UI is included.
119+
### Requisitos Python
163120

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

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

168127
---
169128

170-
### Sentry
171-
172-
Sentry is pre-configured for logging. Set the DSN URL in production.
129+
## Outros
173130

174-
Signup at: [https://sentry.io/signup/?code=cookiecutter](https://sentry.io/signup/?code=cookiecutter)
175-
176-
---
177-
178-
## Deployment
131+
```bash
132+
mypy core # verificação de tipos (não é suite de testes)
133+
```
179134

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

182-
## Download Model
137+
**Deploy:** ver `production.yml` e documentação Docker do projeto.
183138

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

0 commit comments

Comments
 (0)