Expande consideravelmente documentação do repositório

okfn-brasil · Oct 20, 2024 · 50d3be2 · 50d3be2
1 parent 498d67e
commit 50d3be2
Show file tree

Hide file tree

Showing 21 changed files with 452 additions and 41 deletions.
diff --git a/README.md b/README.md
diff --git a/README.md b/README.md
@@ -0,0 +1 @@
+docs/README.md
diff --git a/config/sample.env b/config/sample.env
@@ -22,4 +22,4 @@ APACHE_TIKA_SERVER=http://localhost:9998
 QUERIDO_DIARIO_FILES_ENDPOINT=http://localhost:9000/queridodiariobucket
 
 # Options: ALL, DAILY, UNPROCESSED
-EXECUTION_MODE=DAILY
+EXECUTION_MODE=ALL
diff --git a/docs/CODE_OF_CONDUCT-en-US.md b/docs/CODE_OF_CONDUCT-en-US.md
@@ -0,0 +1,9 @@
+**English (US)** | [Português (BR)](/docs/CODE_OF_CONDUCT.md)
+
+# Contributor Covenant Code of Conduct
+
+We expect all people to respect and be respected, regardless of any diversity.
+
+To ensure this, we have derived this document from the [**Querido Diário Code of Conduct**](https://docs.queridodiario.ok.org.br/en/latest/contributing/code-of-conduct.html).
+
+If you intend to participate in our community, we ask that you read it and follow the guidelines described therein.
diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md
@@ -0,0 +1,9 @@
+**Português (BR)** | [English (US)](/docs/CODE_OF_CONDUCT-en-US.md)
+
+# Código de Conduta de Colaboração
+
+Esperamos que todas as pessoas respeitem e sejam respeitadas, independentemente de qualquer diversidade.
+
+Para garantir isso, derivamos este documento do [**Código de Conduta do Querido Diário**](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/codigo-de-conduta.html).
+
+Caso você tenha o objetivo de participar da nossa comunidade, pedimos que o leia e siga as diretrizes nele descritas.
diff --git a/docs/CONTRIBUTING-en-US.md b/docs/CONTRIBUTING-en-US.md
@@ -0,0 +1,82 @@
+**English (US)** | [Português (BR)](/docs/CONTRIBUTING.md)
+
+# Contributing
+Querido Diario has a [Contribution Guide](https://docs.queridodiario.ok.org.br/en/latest/contributing/contribution-guide.html#contributing) that is relevant to all of its repositories. The guide provides general information about how to interact with the project, the code of conduct you adhere to when contributing, the list of ecosystem repositories and the first actions you can take. We recommend reading it before continuing.
+
+Have you read it? Then let's move on to the specific information about this repository:
+- [Some definitions](#some-definitions)
+- [Structure](#structure)
+- [How to set up the development environment](#how-to-set-up-the-development-environment)
+    - [On Linux](#on-linux)
+- [Maintaining](#maintaining)
+
+## Some definitions
+
+For us to speak the same language, we need to agree on some important terms for the project:
+
+- Resources: Where data can be found and used (Postgres database, Opensearch engine, etc.);
+- Services: Abstractions for accessing and modifying resources (OpensearchInterface, etc.) and other tools (ApacheTikaExtractor);
+- Tasks: Unit (or step) of processing that usually interacts with resources to generate outputs;
+- Pipelines: A set of tasks that fulfills a goal.
+
+## Structure
+
+A brief description of the repository structure:
+
+| **Directory**                         | **Description**                                                                                              |
+|---------------------------------------|--------------------------------------------------------------------------------------------------------------|
+| [`.github`](/.github)                 | Repository settings for GitHub.                                                                              |
+| [`docs`](/docs)                       | Repository documentation files (README, CONTRIBUTING, etc.).                                                 |
+| [`config`](/config)                   | Configuration files such as environment variables and thematic index keywords.                               |
+| [`data_extraction`](/data_extraction) | Interfaces and implementations of services for interacting with data extractors like Apache Tika (text).     |
+| [`database`](/database)               | Interfaces and implementations of services for interacting with databases like Postgres.                     |
+| [`docs`](/docs)                       | Repository documentation files (README, CONTRIBUTING, etc.).                                                 |
+| [`index`](/index)                     | Interfaces and implementations of services for interacting with search engines like Opensearch.              |
+| [`main`](/main)                       | Processing pipelines (to initially understand the project's operation, this is a good starting point).       |
+| [`segmentation`](/segmentation)       | Implementation of text segmenters for diaries (e.g.: 1 municipal association diary -> N municipal diaries).  |
+| [`storage`](/storage)                 | Interfaces and implementations of services for interacting with object storage like Minio.                   |
+| [`tasks`](/tasks)                     | Directory containing tasks to be executed in the pipelines (task definitions are found in their docstrings). |
+| [`tasks/utils`](/tasks/utils)         | Utilities to assist tasks.                                                                                   |
+| [`tests`](/tests)                     | Unit and integration tests (👀).                                                                             |
+
+
+## How to set up the development environment
+
+To set up the development environment, you need the [podman](https://podman.io/) container manager and Python (3.8+).
+
+### On Linux
+
+Before anything else, we use `pre-commit` in the project, so don’t forget to set up a Python virtual environment with it.
+
+1. With Python and podman installed, in the root of the repository, activate the virtual environment:
+
+```console
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+2. Install the development dependencies and install `pre-commit`:
+
+```console
+pip install -r requirements-dev.txt
+pre-commit install
+```
+
+3. Now let's build the images and set up the pod and the resource containers used in the processing:
+
+```console
+make build
+make setup
+```
+
+If you want the processed data to be consumed by the local [Querido Diário API](https://github.com/okfn-brasil/querido-diario-api/) or [Backend](https://github.com/okfn-brasil/querido-diario-backend/), check the [end-to-end setup documentation](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/configuracao-de-ponta-a-ponta.html). In this case, the setup should be done using:
+
+```console
+make build
+FULL_PROJECT=true make setup
+```
+
+4. Done! Now you can start editing the code and running the pipelines.
+
+# Maintaining
+Maintainers must follow the guidelines in Querido Diário's [Guide for Maintainers](https://docs.queridodiario.ok.org.br/en/latest/contributing/contribution-guide.html#maintaining).
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -0,0 +1,82 @@
+**Português (BR)** | [English (US)](/docs/CONTRIBUTING-en-US.md)
+
+# Contribuindo
+O Querido Diário possui um [Guia para Contribuição](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/guia-de-contribuicao.html#contribuindo) principal que é relevante para todos os seus repositórios. Este guia traz informações gerais sobre como interagir com o projeto, o código de conduta que você adere ao contribuir, a lista de repositórios do ecossistema e as primeiras ações que você pode tomar. Recomendamos sua leitura antes de continuar.
+
+Já leu? Então vamos às informações específicas deste repositório:
+- [Algumas definições](#algumas-definições)
+- [Estrutura](#estrutura)
+- [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento)
+    - [Em Linux](#em-linux)
+- [Mantendo](#mantendo)
+
+## Algumas definições
+
+Para que possamos falar a mesma língua, precisamos pactuar alguns termos importantes para o projeto:
+
+- Recursos: Onde dados podem ser encontrados e utilizados (banco Postgres, motor de busca Opensearch, etc.);
+- Serviços: Abstrações para acesso e modificação de recursos (OpensearchInterface, etc.) e outras ferramentas (ApacheTikaExtractor);
+- Tasks (ou tarefas): Unidade (ou etapa) de processamento que geralmente interage com os recursos para gerar suas saídas;
+- Pipelines: Conjunto de tarefas que cumpre um objetivo.
+
+## Estrutura
+
+Uma breve descrição da estrutura do repositório:
+
+| **Diretório**                         | **Descrição**                                                                                                                    |
+|---------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
+| [`.github`](/.github)                 | Configurações do repositório para o GitHub.                                                                                      |
+| [`docs`](/docs)                       | Arquivos de documentação do repositório (README, CONTRIBUTING, etc.).                                                            |
+| [`config`](/config)                   | Arquivos de configuração como variáveis de ambiente e palavras-chave de índices temáticos.                                       |
+| [`data_extraction`](/data_extraction) | Interfaces e implementações de serviços de interação com extratores de dados como o Apache Tika (texto).                         |
+| [`database`](/database)               | Interfaces e implementações de serviços de interação com banco como o Postgres.                                                  |
+| [`docs`](/docs)                       | Arquivos de documentação do repositório (README, CONTRIBUTING, etc.).                                                            |
+| [`index`](/index)                     | Interfaces e implementações de serviços de interação com motores de busca como o Opensearch.                                     |
+| [`main`](/main)                       | Pipelines de processamento (para compreender inicialmente o funcionamento do projeto este é um bom ponto de partida).            |
+| [`segmentation`](/segmentation)       | Implementação de segmentadores do conteúdo textual de diários (ex: 1 diário de associação municipal -> N diários de municípios). |
+| [`storage`](/storage)                 | Interfaces e implementações de serviços de interação com armazenamento de objetos como o Minio.                                  |
+| [`tasks`](/tasks)                     | Diretório que contém as tarefas que serão executadas nos pipelines (definições das tarefas são encontradas em suas docstrings).  |
+| [`tasks/utils`](/tasks/utils)         | Utilitários para auxiliar as tarefas.                                                                                            |
+| [`tests`](/tests)                     | Testes unitários e de integração (👀).                                                                                           |
+
+
+## Como configurar o ambiente de desenvolvimento
+
+Para configurar o ambiente de desenvolvimento, é necessário o gestor de containers [podman](https://podman.io/) e Python (3.8+).
+
+### Em Linux
+
+Antes de qualquer coisa, utilizamos `pre-commit` no projeto, então não se esqueça de configurar de um ambiente virtual Python com ele.
+
+1. Com o Python e podman instalados, na raíz do repositório, ative o ambiente virtual:
+
+```console
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+2. Instale as dependências de desenvolvimento e instale o `pre-commit`:
+
+```console
+pip install -r requirements-dev.txt
+pre-commit install
+```
+
+3. Agora vamos construir as imagens e montar o pod e os containers de recursos utilizados no processamento:
+
+```console
+make build
+make setup
+```
+
+Caso deseje que os dados processados sejam consumidos pela [API](https://github.com/okfn-brasil/querido-diario-api/) ou [Backend](https://github.com/okfn-brasil/querido-diario-backend/) do Querido Diário localmente, acesse a documentação da [configuração de ponta-a-ponta](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/configuracao-de-ponta-a-ponta.html). Assim, a configuração deve ser feita usando:
+
+```console
+make build
+FULL_PROJECT=true make setup
+```
+
+4. Pronto! Agora você já pode começar a editar o código e executar os pipelines.
+
+# Mantendo
+As pessoas mantenedoras devem seguir as diretrizes do [Guia para Mantenedoras](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/guia-de-contribuicao.html#mantendo) do Querido Diário.
diff --git a/docs/FUNDING.yml b/docs/FUNDING.yml
@@ -0,0 +1 @@
+custom: ["https://queridodiario.ok.org.br/apoie/"]