Atualiza documentações do repositório (#1120)

.github/ISSUE_TEMPLATE/revisao_retroativa.yaml

@@ -1,6 +1,6 @@
 name: Revisão retroativa
 description: Dar manutenção em código legado de raspadores no repositório
-title: "[Revisão retroativa]: Raspador de <MUNICÍPIO-UF>"
+title: "[Revisão retroativa]: <MUNICÍPIO-UF>"
 labels: ["refactor"]
 body: 
   - type: dropdown
@@ -10,7 +10,7 @@ body:
       description: Selecione a opção abaixo
       multiple: false
       options:
-        - Neste repositório, há muitos códigos de raspadores que foram desenvolvidos no começo do projeto e não estão sendo usados. Para passar a usar o raspador deste município, é necessário testar para verificar se segue funcionando e revisá-lo caso não esteja. 
+        - Neste repositório, há muitos códigos de raspadores que foram desenvolvidos no começo do projeto e não estão sendo usados. Para passar a usar o raspador deste município, é necessário testar para verificar se segue funcionando e revisá-lo caso não esteja. Consulte a <a href='https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html'>documentação</a> para te ajudar.
     validations:
       required: true
   - type: input
@@ -39,10 +39,3 @@ body:
       placeholder: ex. mês/ano até atualmente; de 2016 à 2020
     validations:
       required: true
-  - type: textarea
-    id: test-list
-    attributes:
-      label: Lista de testes
-      description: "Utilize a lista a seguir de referência para teste. O raspador precisa atender todos os itens para estar pronto para ser usado. \n 1. [ ] Você executou uma extração completa do spider localmente e os dados retornados estavam corretos.\n 2. [ ] Você executou uma extração por período (start_date e end_date definidos) ao menos uma vez e os dados retornados estavam corretos. \n 3. [ ] Você verificou que não existe nenhum erro nos logs (log/ERROR igual a zero).\n 4. [ ] Você definiu o atributo de classe start_date no seu spider com a data do Diário Oficial mais antigo disponível na página da cidade.\n 5. [ ] Você garantiu que todos os campos que poderiam ser extraídos foram extraídos <a href='https://docs.queridodiario.ok.org.br/pt-br/latest/escrevendo-um-novo-spider.html#definicao-de-campos'>de acordo com a documentação</a>.  \n \n Por favor, inclua qualquer informação relevante para o desenvolvimento."
-    validations:
-      required: false

.github/pull_request_template.md

@@ -1,12 +1,27 @@
-**AO ABRIR** um Pull Request de um novo raspador (spider), marque com um `X` cada um dos items do checklist 
-abaixo. **NÃO ABRA** um novo Pull Request antes de completar todos os items abaixo.
-
-#### Checklist - Novo spider
-- [ ] Você executou uma extração completa do spider localmente e os dados retornados estavam corretos.
-- [ ] Você executou uma extração por período (`start_date` e `end_date` definidos) ao menos uma vez e os dados retornados estavam corretos.
-- [ ] Você verificou que não existe nenhum erro nos logs (`log_count/ERROR` igual a zero).
-- [ ] Você definiu o atributo de classe `start_date` no seu spider com a data do Diário Oficial mais antigo disponível na página da cidade.
-- [ ] Você garantiu que todos os campos que poderiam ser extraídos foram extraídos [de acordo com a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/escrevendo-um-novo-spider.html#definicao-de-campos).
+**AO ABRIR** uma *Pull Request* de um novo raspador (*spider*), marque com um `X` cada um dos items da checklist abaixo. Caso algum item não seja marcado, JUSTIFIQUE o motivo.
+
+#### Layout do site publicador de diários oficiais
+Marque apenas um dos itens a seguir:
+- [ ] O *layout* não se parece com nenhum caso [da lista de *layouts* padrão](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/lista-sistemas-replicaveis.html)
+- [ ] É um *layout* padrão e esta PR adiciona a spider base do padrão ao projeto junto com alguns municípios que fazem parte do padrão.
+- [ ] É um *layout* padrão e todos os municípios adicionados usam a [classe de spider base](https://github.com/okfn-brasil/querido-diario/tree/main/data_collection/gazette/spiders/base) adequada para o padrão.
+
+#### Código da(s) spider(s)
+- [ ] O(s) raspador(es) adicionado(s) tem os [atributos de classe exigidos](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#UFMunicipioSpider).
+- [ ] O(s) raspador(es) adicionado(s) cria(m) objetos do tipo Gazette coletando todos [os metadados necessários](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#Gazette).
+- [ ] O atributo de classe [start_date](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#UFMunicipioSpider.start_date) foi preenchido com a data da edição de diário oficial mais antiga disponível no site.
+- [ ] Explicitar o atributo de classe [end_date](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#UFMunicipioSpider.end_date) não se fez necessário.
+- [ ] Não utilizo `custom_settings` em meu raspador.
+
+#### Testes
+- [ ] Uma coleta-teste **da última edição** foi feita. O arquivo de `.log` deste teste está anexado na PR.
+- [ ] Uma coleta-teste **por intervalo arbitrário** foi feita. Os arquivos de `.log`e `.csv` deste teste estão anexados na PR.
+- [ ] Uma coleta-teste **completa** foi feita. Os arquivos de `.log` e `.csv` deste teste estão anexados na PR.
+
+#### Verificações
+- [ ] Eu experimentei abrir alguns arquivos de diários oficiais coletados pelo meu raspador e verifiquei eles [conforme a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#diarios-oficiais-coletados) não encontrando problemas.
+- [ ] Eu verifiquei os arquivos `.csv` gerados pela minha coleta [conforme a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#arquivos-auxiliares) não encontrando problemas.
+- [ ] Eu verifiquei os arquivos de `.log` gerados pela minha coleta [conforme a documentação](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#arquivos-auxiliares) não encontrando problemas.
 
 #### Descrição
 

data_collection/gazette/settings.py

@@ -16,6 +16,8 @@
     "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:108.0) Gecko/20100101 Firefox/108.0"
 )
 
+TEMPLATES_DIR = "templates"
+
 DOWNLOAD_TIMEOUT = 360
 
 FILES_STORE = config("FILES_STORE", default="data")

data_collection/templates/spiders/qdtemplate.tmpl

@@ -0,0 +1,29 @@
+from datetime import date
+
+from gazette.items import Gazette
+from gazette.spiders.base import BaseGazetteSpider
+
+class UFMunicipioSpider(BaseGazetteSpider):
+    name = "$name"
+    TERRITORY_ID = ""
+    allowed_domains = ["$domain"]
+    start_urls = ["$url"]
+    start_date = date()
+
+    def parse(self, response):
+        # Lógica de extração de metadados
+
+        # partindo de response ...
+        #
+        # ... o que deve ser feito para coletar DATA DO DIÁRIO?
+        # ... o que deve ser feito para coletar NÚMERO DA EDIÇÃO?
+        # ... o que deve ser feito para coletar se a EDIÇÃO É EXTRA?
+        # ... o que deve ser feito para coletar a URL DE DOWNLOAD do arquivo?
+
+        yield Gazette(
+            date = date(),
+            edition_number = "",
+            is_extra_edition = False,
+            file_urls = [""],
+            power = "executive",
+        )

docs/CONTRIBUTING.md

@@ -4,10 +4,12 @@
 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:
-- [Contribuindo](#contribuindo)
-  - [Desafios](#desafios)
-  - [Metas do Repositório](#metas-do-repositório)
-  - [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento)
+- [Desafios](#desafios)
+- [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento)
+- [Desafios](#desafios)
+    - [Labels](#labels)
+    - [Metas do Repositório](#metas-do-repositório)
+- [Como configurar o ambiente de desenvolvimento](#como-configurar-o-ambiente-de-desenvolvimento)
     - [Em Linux](#em-linux)
     - [Em Windows](#em-windows)
   - [Formatação automática de código](#formação-automática-de-código)
@@ -17,12 +19,17 @@ Já leu? Então vamos às informações específicas deste repositório:
 ## Desafios
 O principal desafio deste repositório é ter cada vez mais raspadores de sites publicadores de diários oficiais, visando atingir os 5570 municípios brasileiros. Utilizamos o [Quadro de Expansão de Cidades](https://github.com/orgs/okfn-brasil/projects/12/views/13) para organizar o progresso do desafio. Consulte-o para localizar tarefas relevantes com as quais você pode contribuir.
 
-Para te ajudar a desenvolver, utilize as orientações da página sobre [como escrever um novo raspador](https://docs.queridodiario.ok.org.br/pt-br/latest/escrevendo-um-novo-spider.html) disponível na [documentação técnica do Querido Diário](https://docs.queridodiario.ok.org.br/pt-br/latest/).
+Para te ajudar a desenvolver, utilize as orientações da página ["contrbuindo com raspadores"](https://docs.queridodiario.ok.org.br/pt-br/latest/contribuindo/raspadores.html#contribuindo-com-raspadores) disponível na [documentação técnica do Querido Diário](https://docs.queridodiario.ok.org.br/).
 
-## Metas do Repositório
 
+### Labels
+As issues são marcadas com etiquetas, um recurso que serve para classificar issues de mesmo tipo, sinalizar se há algum empecilho ou direcionar a comunidade para tarefas mais do perfil delas. No geral, adotamos *labels* comuns a outros projetos de código aberto como "docs", "bug", "dependencies", mas também temos algumas específicas. Veja quais são na seção de [labels](https://github.com/okfn-brasil/querido-diario/labels)
+
+
+### Metas do Repositório
 Para garantir que nossos esforços estejam alinhados e focados em objetivos claros, definimos metas para o desenvolvimento e expansão do projeto. Estas metas são revisadas e atualizadas regularmente, refletindo as prioridades e os desafios que enfrentamos. Convidamos as pessoas contribuidoras a se familiarizarem com estas metas, disponíveis em nosso [Quadro de Metas](https://github.com/okfn-brasil/querido-diario/milestones). Sua contribuição pode ser ainda mais valiosa quando alinhada com estas direções.
 
+
 ## Como configurar o ambiente de desenvolvimento
 Os raspadores são desenvolvidos usando [Python](https://docs.python.org/3/) e o framework [Scrapy](https://scrapy.org). Você pode conferir [como instalar Python](https://www.python.org/downloads/) em seu sistema operacional e conhecer mais sobre o Scrapy [neste tutorial](https://docs.scrapy.org/en/latest/intro/tutorial.html). Com Python em seu computador, siga o passo-a-passo da configuração do ambiente de desenvolvimento:
 

docs/README.md

@@ -13,6 +13,7 @@ Conheça mais sobre as [tecnologias](https://queridodiario.ok.org.br/tecnologia)
 # Sumário
 - [Como contribuir](#como-contribuir)
 - [Ambiente de desenvolvimento](#ambiente-de-desenvolvimento)
+- [Template para raspadores](#template-para-raspadores)
 - [Como executar](#como-executar)
   - [Dicas de execução](#dicas-de-execução)
 - [Solução de problemas](#solução-de-problemas)
@@ -48,6 +49,21 @@ 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.
 
+# Template para raspadores
+
+Ao invés de começar um arquivo de raspador do zero, você pode inicializar um arquivo de código de raspador já no padrão do Querido Diário, a partir de um template. Para isso, faça: 
+
+1. Vá para o diretório `data_collection`:
+```console
+cd data_collection
+```
+2. Acione o template:
+```console
+scrapy genspider -t qdtemplate <uf_nome_do_municipio> <https://sitedomunicipio...>
+```
+
+Um arquivo `uf_nome_do_municipio.py` será criado no diretório `spiders`, com alguns campos já preenchidos. O diretório é organizado por UF, lembre-se de mover o arquivo para o diretório adequado.
+
 # Como executar
 Para experimentar a execução de um raspador já integrado ao projeto ou testar o que esteja desenvolvendo, siga os comandos: