diff --git a/LICENSE b/LICENSE.md similarity index 93% rename from LICENSE rename to LICENSE.md index 203b768..79f2987 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020 Open Knowledge Foundation Brasil +Copyright (c) 2021 Open Knowledge Brasil - Rede pelo Conhecimento Livre Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md deleted file mode 100644 index e87509b..0000000 --- a/README.md +++ /dev/null @@ -1,62 +0,0 @@ -# querido-diario-api - -______________________________________ - -_[Click here](docs/languages/en-US/README.md) to read this article in english._ -______________________________________ - -Seja bem-vinda(o) ao projeto Querido Diário API! O objetivo deste repositório é manter o código-fonte da API que disponibiliza os diários oficiais raspados pelo [Querido Diário](https://github.com/okfn-brasil/querido-diario). - -## Requisitos - -Todo o projeto é construído e executado em contêineres e é compatível apenas com ambientes Linux (por enquanto). Como executamos tudo dentro de contêineres, você só precisa instalar o [`podman`](https://podman.io/) para rodar localmente em sua máquina. Se você não está familiarizado com o `podman`, você pode pensá-lo como um `docker` /` docker-compose` mais “leve”. Ele existe em quase todos os repositórios de pacotes de distribuição Linux. Por favor, consulte a [documentação do podman](https://podman.io/getting-started/installation.html) para entender como instalá-lo em seus ambientes. Se tiver alguma dificuldade com o podman, fale com a gente! - -## Instalação - -Para poder executar e testar suas alterações no projeto, primeiro você precisa construir a imagem do contêiner usado no desenvolvimento. Para isso, use o seguinte comando: - -``` -make build -``` - -Com isso, você terá uma imagem do contêiner que poderá executar a API localmente no processo de desenvolvimento. - -## Executando - -Para executar a API localmente em sua máquina, use o seguinte comando: - -``` -make run -``` - -Esse comando vai iniciar todos os contêineres necessários para executar a API. Ou seja, ele inicializa o banco de dados e o contêiner da API. Se tudo correr bem, você poderá fazer consultas à API em `localhost:8080/gazettes/` - -ATENÇÃO: Quando você precisar reiniciar a API, apenas interrompa o processo da API e execute o `make rerun` novamente. Não é necessário reiniciar o banco de dados. - -Você pode checar toda a documentação interativa da API em `localhost:8080/docs`. Nessa página, você pode fazer requisições à API diretamente. Mas, para vê-la funcionar, você precisa inserir dados no banco de dados. Há outro comando, `make apisql`, que abre o `psql` e conecta ao banco de dados. Assim, você pode inserir dados usando alguns `INSERT INTO ...` para testar a API ;) - -### Usando o endpoint de ‘sugestões’ - -O endpoint de sugestões no Querido Diário é uma forma de coletar feedback dos usuários e usa o serviço do Mailjet para enviar e-mails. É necessário criar um token de acesso em [Mailjet](www.mailjet.com) para executar a aplicação e enviar e-mails (salve em `config/current.env`). - -## Testes - -Este projeto foi desenvolvido com o paradigma TDD (Test Driven-Development). Isso significa que não há mudanças sem testes. Devemos sempre buscar ter uma cobertura de 100% do código-fonte. Outra maneira de encarar os testes é o seguinte: - -> “Escreva o teste que o força a escrever o código que você já sabe que quer escrever” -> Por Robert C. Martin (a.k.a. Uncle Bob), tradução nossa. - -Para executar os testes, faça o seguinte: - -```bash -make test -``` - -ATENÇÃO: Não é necessário reiniciar a base de teste a cada vez que você quiser executar os testes. Uma vez que o banco de dados esteja em execução, você só precisa rodar o `make retest` novamente. Claro que, se você remover o banco de dados com `make destroydatabse` ou reiniciar a máquina, você terá que iniciar o banco de dados novamente. - -Para checar a cobertura do código: - -```bash -make coverage -``` - diff --git a/docs/CODE_OF_CONDUCT-en-US.md b/docs/CODE_OF_CONDUCT-en-US.md new file mode 100644 index 0000000..1e6d73b --- /dev/null +++ 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://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CODE_OF_CONDUCT-en-US.md). + +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 new file mode 100644 index 0000000..4e9647f --- /dev/null +++ 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://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CODE_OF_CONDUCT.md). + +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 new file mode 100644 index 0000000..a70700a --- /dev/null +++ b/docs/CONTRIBUTING-en-US.md @@ -0,0 +1,7 @@ +**English (US)** | [Português (BR)](/docs/CONTRIBUTING.md) + +# Contributing +Querido Diário has a [Guide for Contributing](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING-en-US.md#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. + +# Maintaining +Maintainers must follow the guidelines in Querido Diário's [Guide for Maintainers](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING-en-US.md#maintaining). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..f3f8aee --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,72 @@ +**Português (BR)** | [English (US)](/docs/CONTRIBUTING-en-US.md) + +# Contribuindo +O Querido Diário possui um [Guia para Contribuição](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#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: +- [Arquitetura](#arquitetura) +- [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento) + - [Em Linux](#em-linux) +- [Testes](#testes) + +## Arquitetura +![arquitetura](/docs/images/arquitetura.png) + + Abaixo, uma breve descrição de seus componentes: +| **Tipo** | **Nome** | **Descrição** | **Dependências** | +|-----------|----------------------------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------------| +| Aplicação | [`api`](/api) | Configuração e criação de endpoints da API. | _serviços e recursos_ | +| Aplicação | [`main`](/main) | Configuração e execução da API. | _api, serviços, módulos e recursos_ | +| Serviço | [`cities`](/cities) | Consultas ao banco do [Censo de Diários Municipais](https://censo.ok.org.br). | Banco de dados do Censo | +| Serviço | [`companies`](/companies) | Consultas ao banco de dados de CNPJ. | database | +| Serviço | [`gazettes`](/gazettes) | Consultas ao índice de busca textual principal do QD. | index | +| Serviço | [`suggestions`](/suggestions) | Envio de emails de sugestão. | Mailjet | +| Serviço | [`themed_excerpts`](/themed_excerpts) | Consultas ao índices de busca textual temáticos do QD. | index | +| Módulo | [`database`](/database) | Classe de interação com bancos de dados Postgres. | Postgres | +| Módulo | [`config`](/config) | Configuração de variáveis de ambiente. | | +| Módulo | [`index`](/index) | Classe de interação com índices Elasticsearch. | Elasticsearch | +| Recurso | Postgres | Banco de dados de CNPJ. Contém informações sobre empresas e sócios cadastrados na Receita Federal. | | +| Recurso | Banco de dados do [Censo](https://censo.ok.org.br) | Banco de dados de municípios. Contém metadados municipais. | | +| Recurso | Elasticsearch | Índices de busca textual. | | +| Recurso | Mailjet | Serviço de envio de email. | | + +## Como configurar o ambiente de desenvolvimento + +### Em Linux + +A API é construída e executada em contêineres [`podman`](https://podman.io/). Para conhecer mais sobre o `podman`, veja esta [postagem da Red Hat](https://www.redhat.com/pt-br/topics/containers/what-is-podman) ou navegue nos [tutoriais](https://docs.podman.io/en/latest/Tutorials.html) de sua documentação. E é desenvolvida em [Python](https://docs.python.org/3/) (3.6+) utilizando as bibliotecas [FastAPI](https://fastapi.tiangolo.com/) e [Pydantic](https://docs.pydantic.dev/), assim como outras bibliotecas que permitem interação com os recursos da tabela acima. + +1. Instale o [`podman`](https://podman.io/) em sua máquina. Ele existe em quase todos os repositórios de pacotes de distribuição Linux. Consulte a [documentação do podman](https://podman.io/getting-started/installation.html) para entender como instalá-lo na distribuição que utiliza. + +2. Abra um terminal no diretório do seu clone deste repositório + +3. Construa a imagem do contêiner usado no desenvolvimento com o seguinte comando: +``` +make build +``` + +4. Pronto! Com isso, você terá uma imagem do contêiner que poderá executar a API localmente no processo de desenvolvimento. + + +## Testes +Este projeto foi desenvolvido com o paradigma TDD (Test Driven-Development). Isso significa que não há mudanças sem testes. Devemos sempre buscar ter uma cobertura de testes de todo código-fonte. Outra maneira de encarar os testes é o seguinte: + +> “Escreva o teste que o força a escrever o código que você já sabe que quer escrever” +> Por Robert C. Martin (a.k.a. Uncle Bob), tradução nossa. + +Para executar os testes, faça o seguinte: + +```bash +make test +``` + +ATENÇÃO: Não é necessário reiniciar a base de teste a cada vez que você quiser executar os testes. Uma vez que o banco de dados esteja em execução, você só precisa rodar o `make retest` novamente. Se você remover o banco de dados com `make destroydatabse` ou reiniciar a máquina, você terá que iniciar o banco de dados novamente. + +Para checar a cobertura do código: + +```bash +make coverage +``` + +# Mantendo +As pessoas mantenedoras devem seguir as diretrizes do [Guia para Mantenedoras](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#mantendo) do Querido Diário. \ No newline at end of file diff --git a/docs/FUNDING.yml b/docs/FUNDING.yml new file mode 100644 index 0000000..b044d62 --- /dev/null +++ b/docs/FUNDING.yml @@ -0,0 +1 @@ +custom: ["https://queridodiario.ok.org.br/apoie/"] diff --git a/docs/README-en-US.md b/docs/README-en-US.md new file mode 100644 index 0000000..0fb3913 --- /dev/null +++ b/docs/README-en-US.md @@ -0,0 +1,56 @@ +**English (US)** | [Português (BR)](/docs/README.md) + +

+ Querido Diário + +

+ +# API + +Find out more about [technologies](https://queridodiario.ok.org.br/tecnologia) and [history](https://queridodiario.ok.org.br/sobre) of the project on the [Querido Diário website](https://queridodiario.ok.org.br) + +# Summary +- [How to contribute](#how-to-contribute) +- [Support](#support) +- [Thanks](#thanks) +- [Open Knowledge Brazil](#open-knowledge-brazil) +- [License](#license) + +# How to contribute +

+ + catarse + +

+ +Thank you for considering contributing to Querido Diário! :tada: + +You can find how to do it at [CONTRIBUTING-en-US.md](/docs/CONTRIBUTING-en-US.md)! + +Also, check the [Querido Diário documentation](https://docs.queridodiario.ok.org.br/pt/latest/index.html) to help you. + +# Thanks +This project is maintained by Open Knowledge Brazil and made possible thanks to the technical communities, the [Ambassadors of Civic Innovation](https://embaixadoras.ok.org.br/), volunteers and financial donors, in addition to partner universities, companies supporters and funders. + +Meet [who supports Querido Diário](https://queridodiario.ok.org.br/apoie#quem-apoia). + +# Open Knowledge Brazil +

+ + Twitter Follow + + + Instagram Follow + + + LinkedIn Follow + +

+ +[Open Knowledge Brazil](https://ok.org.br/) is a non-profit civil society organization whose mission is to use and develop civic tools, projects, public policy analysis and data journalism to promote free knowledge in the various fields of society. + +All work produced by OKBR is openly and freely available. + +# License + +Code licensed under the [MIT License](/LICENSE.md). \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b9ef090 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,103 @@ +**Português (BR)** | [English (US)](/docs/README-en-US.md) + +

+ Querido Diário + +

+ +# API +Dentro do [ecossistema do Querido Diário](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#ecossistema-do-querido-di%C3%A1rio), este repositório é responsável por **manter o código-fonte da API** que disponibiliza os diários oficiais raspados. + +Conheça mais sobre as [tecnologias](https://queridodiario.ok.org.br/tecnologia) e a [história](https://queridodiario.ok.org.br/sobre) do projeto no [site do Querido Diário](https://queridodiario.ok.org.br) + +# Sumário +- [Documentação](#documentação) +- [Como contribuir](#como-contribuir) +- [Ambiente de desenvolvimento](#ambiente-de-desenvolvimento) +- [Como executar](#como-executar) + - [Usando o endpoint de ‘sugestões’](#usando-o-endpoint-de-sugestões) +- [Testes](#testes) +- [Suporte](#suporte) +- [Agradecimentos](#agradecimentos) +- [Open Knowledge Brasil](#open-knowledge-brasil) +- [Licença](#licença) + +# Como contribuir +

+ + catarse + +

+ +Agradecemos por considerar contribuir com o Querido Diário! :tada: + +Você encontra como fazê-lo no [CONTRIBUTING.md](/docs/CONTRIBUTING.md)! + +Além disso, consulte a [documentação do Querido Diário](https://docs.queridodiario.ok.org.br/pt/latest/index.html) para te ajudar. + +# Documentação +Veja a documentação da API em [queridodiario.ok.org.br/api/docs](https://queridodiario.ok.org.br/api/docs) + +# Ambiente de desenvolvimento + +No momento, o projeto é compatível apenas com ambientes Linux. Ele é construído e executado em contêineres [`podman`](https://podman.io/). A API é desenvolvida em [Python](https://docs.python.org/3/) (3.6+) utilizando as bibliotecas [FastAPI](https://fastapi.tiangolo.com/) e [Pydantic](https://docs.pydantic.dev/). + +Com o `podman`instalado em sua máquina, utilize o comando a seguir em um terminal aberto na raiz do repositório para construir a imagem do contêiner da API: + +``` +make build +``` + +> Veja a seção "[como configurar o ambiente de desenvolvimento](/docs/CONTRIBUTING.md#como-configurar-o-ambiente-de-desenvolvimento)" para mais detalhes, incluindo informações para quem deseja contribuir com o desenvolvimento do repositório. + + +# Como executar +Para executar a API localmente em sua máquina, use o seguinte comando: +``` +make run +``` + +Esse comando iniciará todos os contêineres necessários para executar a API. Ou seja, ele inicializa o banco de dados e o contêiner da API. Se tudo correr bem, você poderá fazer consultas à API em `localhost:8080/gazettes/` + +> ATENÇÃO: Quando você precisar reiniciar a API, apenas interrompa o processo da API e execute o `make rerun` novamente. Não é necessário reiniciar o banco de dados. + +Você pode checar toda a documentação interativa da API em `localhost:8080/docs`. Nessa página, você pode fazer requisições à API diretamente. Mas, para vê-la funcionar, você precisa inserir dados no índice. Há outro comando, `make load-data`, que insere alguns exemplos de entrada no índice principal. + +## Usando o endpoint de ‘sugestões’ + +O endpoint de sugestões no Querido Diário é uma forma de coletar feedback dos usuários e usa o serviço do Mailjet para enviar e-mails. É necessário criar um token de acesso em [Mailjet](www.mailjet.com) para executar a aplicação e enviar e-mails (salve em `config/current.env`). + +# Suporte +

+ + Discord Invite + +

+ +Ingresse em nosso [canal de comunidade](https://go.ok.org.br/discord) para trocas sobre os projetos, dúvidas, pedidos de ajuda com contribuição e conversar sobre inovação cívica em geral. + +# Agradecimentos +Este projeto é mantido pela Open Knowledge Brasil e possível graças às comunidades técnicas, às [Embaixadoras de Inovação Cívica](https://embaixadoras.ok.org.br/), às pessoas voluntárias e doadoras financeiras, além de universidades parceiras, empresas apoiadoras e financiadoras. + +Conheça [quem apoia o Querido Diário](https://queridodiario.ok.org.br/apoie#quem-apoia). + +# Open Knowledge Brasil +

+ + Twitter Follow + + + Instagram Follow + + + LinkedIn Follow + +

+ +A [Open Knowledge Brasil](https://ok.org.br/) é uma organização da sociedade civil sem fins lucrativos, cuja missão é utilizar e desenvolver ferramentas cívicas, projetos, análises de políticas públicas, jornalismo de dados para promover o conhecimento livre nos diversos campos da sociedade. + +Todo o trabalho produzido pela OKBR está disponível livremente. + +# Licença + +Código licenciado sob a [Licença MIT](/LICENSE.md). \ No newline at end of file diff --git a/docs/SUPPORT-en-US.md b/docs/SUPPORT-en-US.md new file mode 100644 index 0000000..ee11909 --- /dev/null +++ b/docs/SUPPORT-en-US.md @@ -0,0 +1,5 @@ +**English (US)** | [Português (BR)](/docs/SUPPORT.md) + +# Support + +Join our [community on Discord](https://go.ok.org.br/discord) to get help. diff --git a/docs/SUPPORT.md b/docs/SUPPORT.md new file mode 100644 index 0000000..c6ef0f0 --- /dev/null +++ b/docs/SUPPORT.md @@ -0,0 +1,5 @@ +**Português (BR)** | [English (US)](/docs/SUPPORT-en-US.md) + +# Suporte + +Junte-se à nossa [comunidade no Discord](https://go.ok.org.br/discord) para obter ajuda. diff --git a/docs/images/architecture.png b/docs/images/architecture.png new file mode 100644 index 0000000..77ae3c2 Binary files /dev/null and b/docs/images/architecture.png differ diff --git a/docs/images/arquitetura.png b/docs/images/arquitetura.png new file mode 100644 index 0000000..e339a8e Binary files /dev/null and b/docs/images/arquitetura.png differ diff --git a/docs/images/querido-diario-logo.png b/docs/images/querido-diario-logo.png new file mode 100644 index 0000000..e75a9b4 Binary files /dev/null and b/docs/images/querido-diario-logo.png differ diff --git a/docs/languages/en-US/README.md b/docs/languages/en-US/README.md deleted file mode 100644 index 26df0e3..0000000 --- a/docs/languages/en-US/README.md +++ /dev/null @@ -1,61 +0,0 @@ -# querido-diario-api - -Welcome to the Querido Diário API project! The goal of this repository is keep the source code used to build the API used to make available the gazettes crawled by the [Querido Diário](https://github.com/okfn-brasil/querido-diario) project. - -## Requisites - -The whole project is build and run inside containers and is supported only in Linux environments (for now). As we run everything inside containers you just need to install [`podman`](https://podman.io/) to run locally in your machine. If you are not familiarize with `podman`, you can think it as a lightweight `docker`/`docker-compose`. It exists in almost all Linux distributions packages repositories. - -Please, check podman [documentation](https://podman.io/getting-started/installation.html) to see how to installed it in your environments. If you face some difficulties with podman, let us know! - -## Build - -In order to be able to run and test your changes in the project, first, you need to build the container image used during development. For that you can use the following command: - -``` -make build -``` - -After that you will have a container image which can be use to run the API locally during development. - -## Running - -To run the API locally in your machine, you can run the following command: - -``` -make run -``` - -This command will start all containers necessary to run the API. In other words, it starts the database and the API container. If everything goes fine, you should be able to query the API at `localhost:8080/gazettes/` - -NOTE: When you want to restart the API, just quit the API process and execute `make rerun` again. You do not need to restart the database. - -You can all check the interactive documentation at `localhost:8080/docs`. Using the docs page, you can all send request to the API. But to see it working you need to insert data into the database. There is another make target, `make apisql`, which open the `psql` and connect to the database. Thus, you can insert data using some `INSERT INTO ...` statements and test the API. ;) - - -### Using suggestion endpoint - -The suggestion endpoint in Querido Diário is a way to collect feedback from users and uses the Mailjet service to send e-mails. You need to create a token at [Mailjet](www.mailjet.com) to run application and send email (put on `config/current.env`). - -## Tests - -The project uses TDD during development. This means that there are no changes without tests. We should always seek 100% source code coverage. Another way to think about tests is the following: - -> "Write the test which forces you to write the code which you already know that you wanna write." -> By Robert C. Martin (a.k.a. Uncle Bob) - -To run the tests you can do the following: - -```bash -make test -``` - -NOTE: You do not need to restart the test database all the times you want to run the tests. Once the database is running, you need to run the `make retest` again. - -You should do that just the first time you run the tests. After that, you can just run `make retest`. Of course, if you remove the database with `make destroydatabse` or reboot the machine, you need to start the database again. - -If you want to see the code coverage: - -```bash -make coverage -```