O Diário Oficial é uma publicação oficial onde a cidade, o estado ou a União (governo federal) deve comunicar para a população todas as decisões e informações relevantes, como contratos firmados, pessoas aprovadas em um concurso ou alterações no orçamento. Podemos dizer que os Diários Oficiais são uma das ferramentas mais antigas na transparência - o primeiro Diário Oficial foi publicado em 1808!

Corta para 2020: onde estamos com os diários hoje? Infelizmente, não existe um formato padrão para os Diários Oficiais; cada lugar tem autonomia para publicar no formato que quiser: HTML, PDF em texto, PDF em imagem… E também com a estrutura que quiser. Agora imagine o que poderíamos fazer tendo informações das mais de 5 mil cidades do Brasil, de maneira buscável e estruturada? Essa é a proposta do Querido Diário! ❤️

O Querido Diário é um projeto de código aberto onde qualquer pessoa pode contribuir. Você também pode contribuir com esse projeto fantástico e acelerar o seu desenvolvimento através da campanha de financiamento coletivo no Catarse. Mas, caso você queira contribuir com código, esse texto é para você. Vem comigo!

Quero contribuir - por onde eu começo?

Pré-requisitos para rodar o projeto: ter o Git e, no mínimo, o Python 3.6 instalados na sua máquina.

Primeiro, você precisa ter conhecimentos de Git para modificar o código do projeto. Caso você ainda não tenha contribuído para nenhum projeto de código aberto, pode começar criando uma conta no Github e vendo esse material que a galera do PUG-PE criou.

Tudo certo com o git: ✅. Você não precisa se aprofundar muito pois o básico é o suficiente para começar. A galera do Querido Diário preparou uma documentação bacana e uns atalhos para a gente contribuir sem medo. Vamos nessa?

Spiders?🕷

Calma, antes de começarmos mesmo, precisamos falar sobre spiders. Você vai ouvir muito essa nomenclatura no projeto, por isso é importante entender do que se trata.

Lembra que falamos que os diários não são estruturados e quem vem de fontes diferentes pois cada lugar tem autonomia para publicar como e onde quiser? Pois é, isso traz um grande desafio tecnológico para o projeto. Precisamos escrever um programa que raspe os dados dos sites de cada cidade e transforme-os em um formato que seja comum a todos. Esse programa que raspa dados de um site é chamado de spider (aranha em inglês). Essa “aranha” vai passeando pelas estruturas HTML que nós especificamos e coleta as informações que queremos. Particularmente, é uma das coisas que eu acho mais legais de fazer enquanto programadora. :)

Não vou mentir para vocês: no início pode parecer meio esquisito, principalmente se a estrutura das páginas do site não forem boas. Mas sabendo um tico de HTML já é o suficiente para você entender melhor. Quer uma dica? Se você nunca fez isso, vá até a página do Diário Oficial da sua cidade e clique com o botão direito do mouse. Clicou? Você deve ver a opção “Ver código fonte da página”. Viu quanta coisa tem? Pois é. Visualizar diretamente o código fonte da página é a maneira mais fiel de conferir os elementos; nem sempre a ferramenta que vamos utilizar irá renderizar o HTML da mesma forma e precisamos saber como investigar possíveis discrepâncias.

Vamos usar uma opção que nos ajude a encontrar o elemento HTML exato. Procure informações que você já tinha visto na página, como a edição do Diário. Clique com o botão direito do mouse e então na opção “Inspecionar “. Uma janela será aberta indicando o elemento correto. Clicou? Certo mas como transformar isso em código? Calma lá, vamos a continuação dessa dica. Ainda na janela do inspecionador, clique com o botão direito no elemento HTML que você havia escolhido e na opção “Copiar” você pode ver diversas opções: Copiar “CSS Path”, “Copiar XPath”…

Opção "Copiar" do "Inspecionar Elemento"

No exemplo, o Diário Oficial da cidade de Feira de Santana - BA.

Esses seletores serão úteis ao escrever um spider pois serão o caminho exato para os elementos que precisamos!

Scrapy

Agora que você já tem uma noção de como descobrir o elemento na página já pode partir para a próxima etapa: o tutorial do Scrapy (em inglês). O Scrapy é um framework poderoso que serve para facilitar a raspagem de dados. O tutorial do Scrapy é uma das fontes mais confiáveis para aprender como criar spiders e como raspar dados da web. Se possível, leia o tutorial e vá executando o código. Após passar pelo tutorial você estará mais que pronta para criar seus próprios spiders no Querido Diário.

Antes de codar…

Caramba, quanto rodeio, hein? :) Calma, tudo isso é para que você caminhe pelo projeto da melhor maneira possível. Digamos que você já tem tudo configurado e pronto para a ação. Isso é ótimo! Mas agora vem uma parte importante: já sabe qual a cidade você quer raspar dados? Se sim ou se não, cheque os passos:

Verifique se a cidade que você quer colaborar já está no censo; se não estiver, é legal adicionar lá. Ao ajudar no mapeamento você também vai coletar informações importantes para a sua contribuição!
Depois de checar o censo, verifique se já existe um spider no repositório: https://github.com/okfn-brasil/querido-diario/tree/main/data_collection/gazette/spiders ou aguardando merge: https://github.com/okfn-brasil/querido-diario/pulls
Não existe ainda? Yay! Crie uma nova issue para sinalizar que você trabalhará nela (exemplo: okfn-brasil/querido-diario: Issue #299)

Seguindo esses passos, imaginamos que você encontrou uma das 5.070 cidades que ainda não tem um spider pronto. Uhuu!

Hora do show

No repositório do Querido Diário você encontrará um guia de contribuição (em inglês). Lá tem informação atualizada de como fazer a configuração inicial do projeto e explorar o site que você quer raspar. No README você encontra também informações valiosas como dicas e o que fazer em alguns casos de erros.

Outras dicas que eu acho legais são:

Crie sempre uma branch no seu fork do projeto, assim você pode trabalhar em coisas diferentes localmente e sua branch principal (main) estará em um estado sempre parecido com a do repositório do projeto;
Nessa página do Wiki você encontra o código da cidade no IBGE, informação obrigatória na adição de um spider (será usada no campo TERRITORY_ID);
Atenção aos padrões de nomes: as classes devem seguir o padrão <SiglaDoEstado><NomeDaCidade>Spider e o nome do arquivo sigladoestado_nomedacidade.py. Sim, o padrão de maiúsculas e minúsculas deve ser seguido;
Ao preparar um pull request, certifique-se de que você rodou o spider todo e sem erros pelo menos uma vez na sua máquina. Isso ajuda bastante ao ter spiders confiáveis no repositório e diminui a carga de trabalho dos mantenedores do projeto;
Ainda sobre criar um novo pull request, adicione uma boa descrição: qual a cidade e estado e informações relevantes para os mantenedores. É legal ter o comando de execução também; :)
Se você quiser exportar os dados do seu spider local, pode executá-lo com um cd data_collection && scrapy crawl <nome do seu spider> -o diarios.csv";
Além da aba de inspeção, as ferramentas da pessoa desenvolvedora inclusa nos navegadores também costumam a ter a aba de Rede (Network). Lá você pode ver quais requisições foram disparadas ao clicar em um botão, por exemplo. Isso pode ser útil ao explorar um novo site.

É isso aí!

Espero que esse texto tenha te ajudado a começar a contribuir para esse projeto tão importante para o Brasil. Boa sorte com as raspagens e muito bem-vindos ao Querido Diário!