From 3394c22264ef8c2f6ef3c4b6f8001c51187741a8 Mon Sep 17 00:00:00 2001 From: Victor Wildner Date: Tue, 10 Oct 2023 21:28:21 -0300 Subject: [PATCH] docs: document the Makefile - Add helper tooltip to makefile - Add description to every command - Add phony protection to commands - Create make install command - Streamline the installation proccess using a single document --- Makefile | 85 ++++++++++++++++++++++++++++++++++---------- docs/README-en-US.md | 18 +++++++--- docs/README.md | 41 ++++++++++++--------- 3 files changed, 104 insertions(+), 40 deletions(-) diff --git a/Makefile b/Makefile index b562c2f33..abb0f2639 100644 --- a/Makefile +++ b/Makefile @@ -1,32 +1,79 @@ +# Define cores para o terminal. +BOLD := $(shell tput bold) +RED := $(shell tput -Txterm setaf 1) +GREEN := $(shell tput -Txterm setaf 2) +BLUE := $(shell tput -Txterm setaf 6) +RESET := $(shell tput -Txterm sgr0) + +# Define argumentos do isort ISORT_ARGS := --combine-star --combine-as --order-by-type --thirdparty scrapy --multi-line 3 --trailing-comma --force-grid-wrap 0 --use-parentheses --line-width 88 +# Define diretório de dados. SRC_DIRS := ./data_collection -check: - python3 -m isort --check --diff $(ISORT_ARGS) $(SRC_DIRS) - python3 -m black --check $(SRC_DIRS) - flake8 $(SRC_DIRS) +# Define o nome do ambiente virtual. +VENV_DIR = $(shell pwd)/.venv/bin/activate + +# Proteção contra comandos que possam ter o mesmo nome de variáveis +.PHONY: all help check format run_spider sql clean shell run_spider_since compile install + +all: install + +help: ## Mostra ajuda para os comandos do Makefile. + @echo "$(BOLD)$(BLUE)Comandos disponíveis:$(RESET)" + @awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z0-9 -]+:.*?## / {printf "$(BOLD)$(GREEN)%-20s$(RESET)%s\n", $$1, $$2}' $(MAKEFILE_LIST) -format: - python3 -m isort --apply $(ISORT_ARGS) $(SRC_DIRS) - python3 -m black $(SRC_DIRS) +install: .venv/bin/activate ## Prepara o ambiente de desenvolvimento. + @python3 -m pip install --upgrade pip -run_spider: - cd $(SRC_DIRS) && scrapy crawl $(SPIDER) +check: ## Verifica os estilos de código com isort, black, e flake8. + @echo "$(BOLD)$(BLUE)Verificando estilos e formatos...$(RESET)" + . $(VENV_DIR) + @python3 -m isort --check --diff $(ISORT_ARGS) $(SRC_DIRS) || echo "$(RED)Checagem do isort falhou$(RESET)" + @python3 -m black --check $(SRC_DIRS) || echo "$(RED)Checkagem do black falhou$(RESET)" + @flake8 $(SRC_DIRS) || echo "$(RED)Checagem do flake8 falhou$(RESET)" -sql: - cd $(SRC_DIRS) && sqlite3 querido-diario.db +format: ## Formata o código usando isort e black. + @echo "$(BOLD)$(BLUE)Formatando o código...$(RESET)" + . $(VENV_DIR) + @python3 -m isort --apply $(ISORT_ARGS) $(SRC_DIRS) || echo "$(RED)Formatação do isort falhou$(RESET)" + @python3 -m black $(SRC_DIRS) || echo "$(RED)Formatação do black falhou$(RESET)" -clean: - find ./$(SRC_DIRS)/data/* -type d -exec rm -rv {} \; +run_spider: ## Roda um spider do Scrapy. + @echo "$(BOLD)$(BLUE)Rodando Spider: $(SPIDER)...$(RESET)" + . $(VENV_DIR) + @cd $(SRC_DIRS) && scrapy crawl $(SPIDER) -shell: - cd $(SRC_DIRS) && scrapy shell +sql: ## Inicia o shell interativo do SQLite3. + @echo "$(BOLD)$(BLUE)Inicializando SQLite3 shell...$(RESET)" + . $(VENV_DIR) + @cd $(SRC_DIRS) && sqlite3 querido-diario.db -run_spider_since: - cd $(SRC_DIRS) && scrapy crawl -a start_date=$(START_DATE) $(SPIDER) +clean: ## Limpando os diretórios de dados. + @echo "$(BOLD)$(BLUE)Limpando o diretório de dados...$(RESET)" + . $(VENV_DIR) + @find ./$(SRC_DIRS)/data/* -type d -exec rm -rv {} \; + @echo "$(GREEN)Limpeza completa.$(RESET)" -compile: - cd data_collection; \ +shell: ## Inicia o shell interativo do Scrapy. + @echo "$(BOLD)$(BLUE)Inicializando o shell interativo...$(RESET)" + . $(VENV_DIR) + @cd $(SRC_DIRS) && scrapy shell + +run_spider_since: ## Roda um spider do Scrapy com data de início. + @echo "$(BOLD)$(BLUE)Inicializando spider com data definida: $(START_DATE)...$(RESET)" + . $(VENV_DIR) + @cd $(SRC_DIRS) && scrapy crawl -a start_date=$(START_DATE) $(SPIDER) + +compile: ## Compila os arquivos requirements.in e requirements-dev.in. + @echo "$(BOLD)$(BLUE)Compilando requerimentos, por favor aguarde...$(RESET)" + . $(VENV_DIR) + @cd data_collection; \ pip-compile --upgrade --no-annotate --allow-unsafe --generate-hashes requirements.in; \ pip-compile --upgrade --no-annotate --allow-unsafe --generate-hashes requirements-dev.in + +.venv/bin/activate: data_collection/requirements-dev.txt + @echo "$(BOLD)$(BLUE)Preparando ambiente de desenvolvimento, por favor aguarde...$(RESET)" + @python3 -m venv .venv + @. $(VENV_DIR) + pip install -r data_collection/requirements-dev.txt && pre-commit install || echo "$(RED)Erro ao instalar dependências.$(RESET)" diff --git a/docs/README-en-US.md b/docs/README-en-US.md index aceb17922..250e196ac 100644 --- a/docs/README-en-US.md +++ b/docs/README-en-US.md @@ -1,4 +1,4 @@ -**English (US)** | [Português (BR)](/docs/README.md) +**English (US)** | [Português (BR)](/docs/README.md)

Querido Diário @@ -21,11 +21,11 @@ Find out more about [technologies](https://queridodiario.ok.org.br/tecnologia) a - [License](#license) # How to contribute -

- +

+ catarse -

+

Thank you for considering contributing to Querido Diário! :tada: @@ -38,6 +38,14 @@ You need to have [Python](https://docs.python.org/3/) (+3.0) and [Scrapy](https: The commands below set it up in Linux operating system. They consist of creating a [virtual Python environment](https://docs.python.org/3/library/venv.html), installing the requirements listed in `requirements-dev` and the code standardization tool `pre-commit`. +Run the make command to get the entire environment ready: + +```sh +make +``` + +Alternatively, you can run the commands below to create the virtual environment and install the requirements: + ``` console python3 -m venv .venv source .venv/bin/activate @@ -115,4 +123,4 @@ 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 +Code licensed under the [MIT License](/LICENSE.md). diff --git a/docs/README.md b/docs/README.md index d8db36e80..9f98e2b53 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -**Português (BR)** | [English (US)](/docs/README-en-US.md) +**Português (BR)** | [English (US)](/docs/README-en-US.md)

Querido Diário @@ -22,23 +22,32 @@ Conheça mais sobre as [tecnologias](https://queridodiario.ok.org.br/tecnologia) - [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. +Além disso, consulte a [documentação do Querido Diário](https://docs.queridodiario.ok.org.br/pt/latest/index.html) para te ajudar. # Ambiente de desenvolvimento -Você precisa ter [Python](https://docs.python.org/3/) (+3.0) e o framework [Scrapy](https://scrapy.org) instalados. +Você precisa ter [Python](https://docs.python.org/3/) (+3.0) e o framework [Scrapy](https://scrapy.org) instalados. Os comandos abaixo preparam o ambiente em sistema operacional Linux. Eles consistem em criar um [ambiente virtual de Python](https://docs.python.org/pt-br/3/library/venv.html), instalar os requisitos listados em `requirements-dev` e a ferramenta para padronização de código `pre-commit`. +Rode a ferramenta `make` para preparar o ambiente completo: + +```sh +make + +``` + +Alternativamente, você pode executar os comandos abaixo para criar o ambiente virtual e instalar os requisitos: + ``` console python3 -m venv .venv source .venv/bin/activate @@ -49,7 +58,7 @@ pre-commit install > A configuração em outros sistemas operacionais está disponível em ["como configurar o ambiente de desenvolvimento"](/docs/CONTRIBUTING.md#como-configurar-o-ambiente-de-desenvolvimento), incluindo mais detalhes para quem deseja contribuir com o desenvolvimento do repositório. # Como executar -Para experimentar a execução de um raspador já integrado ao projeto ou testar o que esteja desenvolvendo, siga os comandos: +Para experimentar a execução de um raspador já integrado ao projeto ou testar o que esteja desenvolvendo, siga os comandos: 1. Se ainda não o fez, ative o ambiente virtual no diretório `/querido-diario`: ``` console @@ -70,9 +79,9 @@ scrapy crawl //exemplo: scrapy crawl ba_acajutiba 5. Os diários coletados na raspagem serão salvos no diretório `data_collection/data` ## Dicas de execução -Além dos comandos acima, o Scrapy oferece outros recursos para configurar o comando de raspagem. Os recursos a seguir podem ser usados sozinhos ou combinados. +Além dos comandos acima, o Scrapy oferece outros recursos para configurar o comando de raspagem. Os recursos a seguir podem ser usados sozinhos ou combinados. -* **Limite de data** +* **Limite de data** Ao executar o item 4, o raspador coletará todos os diários oficiais do site publicador daquele município. Para execuções menores, utilize a flag de atributo `-a` seguida de: `start_date=AAAA-MM-DD`: definirá a data inicial de coleta de diários. @@ -84,24 +93,24 @@ scrapy crawl -a start_date= scrapy crawl -a end_date= ``` -* **Arquivo de log** +* **Arquivo de log** É possível enviar o log da raspagem para um arquivo ao invés de deixá-lo no terminal. Isto é particularmente útil quando se desenvolve um raspador que apresenta problemas e você quer enviar o arquivo de log no seu PR para obter ajuda. Para isso, use a flag de configuração `-s` seguida de: `LOG_FILE=log_.txt`: definirá o arquivo para armazenar as mensagens de log. ```console scrapy crawl -s LOG_FILE=log_.txt ``` -* **Tabela de raspagem** +* **Tabela de raspagem** Também é possível construir uma tabela que lista todos os diários e metadados coletados pela raspagem, ficando mais fácil de ver como o raspador está se comportando. Para isso, use a flag de saída `-o` seguida de um nome para o arquivo. ```console scrapy crawl -o .csv ``` # Solução de problemas -Confira o arquivo de [solução de problemas](/docs/TROUBLESHOOTING.md) para resolver os problemas mais frequentes com a configuração do ambiente do projeto. +Confira o arquivo de [solução de problemas](/docs/TROUBLESHOOTING.md) para resolver os problemas mais frequentes com a configuração do ambiente do projeto. -# Suporte -

+# Suporte +

Discord Invite @@ -127,10 +136,10 @@ Conheça [quem apoia o Querido Diário](https://queridodiario.ok.org.br/apoie#qu

-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. +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 +Código licenciado sob a [Licença MIT](LICENSE.md).