From e05162476c094efddeefac0999e1b2021bfb6a3a Mon Sep 17 00:00:00 2001 From: Eduardo Lauer Date: Wed, 26 Jun 2024 18:10:37 -0300 Subject: [PATCH] update docs --- docs/docs/como_funciona/exemplos/exemplos.md | 241 ++++++++++++++++++ .../index.md} | 0 docs/docs/como_funciona/operadores.md | 3 + docs/docs/como_funciona/parametros.md | 39 +++ .../instalacao/instalacao.md} | 43 +--- .../instalacao/notificacao_de_erros.md | 12 + docs/docs/como_utilizar/introducao.md | 8 + docs/docs/como_utilizar/usuarios.md | 17 ++ docs/mkdocs.yml | 21 +- 9 files changed, 337 insertions(+), 47 deletions(-) create mode 100644 docs/docs/como_funciona/exemplos/exemplos.md rename docs/docs/{funcionamento.md => como_funciona/index.md} (100%) create mode 100644 docs/docs/como_funciona/operadores.md create mode 100644 docs/docs/como_funciona/parametros.md rename docs/docs/{utilizacao.md => como_utilizar/instalacao/instalacao.md} (67%) create mode 100644 docs/docs/como_utilizar/instalacao/notificacao_de_erros.md create mode 100644 docs/docs/como_utilizar/introducao.md create mode 100644 docs/docs/como_utilizar/usuarios.md diff --git a/docs/docs/como_funciona/exemplos/exemplos.md b/docs/docs/como_funciona/exemplos/exemplos.md new file mode 100644 index 0000000..8d81afc --- /dev/null +++ b/docs/docs/como_funciona/exemplos/exemplos.md @@ -0,0 +1,241 @@ +## Exemplos de configuração do arquivo YAML + +Neste segmento, você encontrará uma série de exemplos práticos de utilização do Ro-DOU. A leitura dos exemplos ajudará a visualizar de que maneira o Ro-DOU pode ser utilizado. + +### Exemplo 1 + +A configuração a seguir cria uma DAG que realiza a pesquisa **diária** dos +**6 termos listados** e envia o relatório para o **e-mail** fornecido. + +```yaml +dag: + id: pesquisa_dou_termos_interesse_nitai + description: Pesquisa termos de interesse de Nitai. + search: + terms: + - dados abertos + - governo aberto + - engenharia de dados + - software livre + - código aberto + - open source + report: + emails: + - endereco@dominio.com +``` + +### Exemplo 2 + +A configuração a seguir realiza a pesquisa diária de **segunda-feira a sexta-feira, 8AM**, apenas na **Seção 1 e na Edição Suplementar** e envia o resultado em **formato CSV**, anexado ao e-mail. O parâmetro `schedule` +aceita valores CRON. + +```yaml +dag: + id: dag_id_deve_ser_unico_em_todo_airflow + description: DAG exemplo de monitoramento no DOU. + schedule: 0 8 * * MON-FRI + search: + terms: + - alocação + - realoca + - permuta + - estrutura regimental + - organização básica + dou_sections: + - SECAO_1 + - EDICAO_SUPLEMENTAR + report: + emails: + - dest1@gestao.gov.br + - dest2@gestao.gov.br + attach_csv: True + subject: Assunto do Email +``` + +Note que aqui são utilizados os parâmetros opcionais `schedule`, +`dou_section` e `attach_csv`. + +### Exemplo 3 + +A configuração a seguir utiliza o parâmetro `from_db_select` em `terms`, que torna dinâmica a parametrização dos termos para pesquisa. Note também a inclusão de `tags` que ajudam na organização e na busca das DAGs no Airflow. + +```yaml +dag: + id: dag_ultra_dinamica + description: A pesquisa depende do select SQL. + tags: + - projeto_a + - departamento_x + search: + terms: + from_db_select: + sql: SELECT text FROM schema.tabela; + conn_id: airflow_conn_id + report: + emails: + - email-destino@gestao.gov.br + subject: "[String] com caracteres especiais deve estar entre aspas" +``` + +### Exemplo 4 + +A configuração a seguir utiliza o parâmetro `from_airflow_variable` em `terms`, que também carrega dinamicamente a lista de termos. Neste caso, há a recuperação a partir de uma **variável do Airflow**. Aqui, também é utilizado o campo `field` para limitar as pesquisas ao campo título das publicações no Diário Oficial da União. + +```yaml +dag: + id: pesquisa_a_lista_na_variavel + description: É fácil editar a variável na interface do Airflow. + search: + terms: + from_airflow_variable: nome_da_variavel_no_airflow + field: TITULO + report: + emails: + - email-destino@gestao.gov.br + skip_null: False +``` +Caso não encontre nenhum resultado, será enviado um e-mail informando que +nenhum termo foi encontrado. + + +### Exemplo 5 + +A configuração a seguir produz uma DAG que executa apenas **uma vez por mês**, no dia 1 às 8 AM, como pode ser visto no `schedule`. Simultaneamente, a pesquisa no Diário Oficial da União é realizada nos diários oficiais do **último mês** inteiro, através do uso do parâmetro `date`. Aqui, também é utilizado o parâmetro `is_exact_search` +com valor `False` para utilizar uma pesquisa aproximada. + +Apesar do fato de que o termo buscado "paralelpip**i**do" contenha um erro ortográfico, a busca retorna os resultados corretos. [Veja!](https://www.in.gov.br/consulta/-/buscar/dou?q=ddm__text__21040__texto_pt_BR-paralelepipido&s=todos&exactDate=ano&sortType=0) + +```yaml +dag: + id: relatorio_mensal_do_dou + description: Envia um numero menor de emails. + schedule: 0 8 1 * * + search: + terms: + - paralelpipido + date: MES + is_exact_search: False + report: + emails: + - email-destino@gestao.gov.br +``` + +### Exemplo 6 + +A configuração a seguir produz uma DAG que pesquisa no Querido Diário pelos termos "pandemia", "dados pessoais" e "prefeitura", buscando apenas os resultados do Diário Oficial de Belo Horizonte. Para conhecer o Querido Diário, acesse +[https://queridodiario.ok.org.br/](https://queridodiario.ok.org.br/). + +```yaml +dag: + id: dou_qd_example + description: DAG de teste + search: + sources: + - QD + territory_id: 3106200 # Belo Horizonte + terms: + - pandemia + - dados pessoais + - prefeitura + report: + emails: + - destination@gestao.gov.br + attach_csv: True + subject: "Teste do Ro-dou" +``` + +### Exemplo 7 + +A configuração a seguir produz uma DAG exatamente igual ao exemplo básico, mas adiciona uma descrição longa do que a DAG faz, usando o parâmetro +`doc_md`. Essa descrição pode conter formatação markdown, incluindo +títulos, listas, links etc. + +Além disso, acrescenta também uma referência ao nome do arquivo que +gerou a DAG, bem como os seus parâmetros. + +```yaml +dag: + id: markdown_docs_example + description: DAG com documentação em markdown + search: + terms: + - dados abertos + - governo aberto + - lei de acesso à informação + report: + emails: + - destination@gestao.gov.br + subject: "Teste do Ro-dou" + doc_md: >- + ## Ola! + + Esta é uma DAG de exemplo com documentação em markdown. Esta + descrição é opcional e pode ser definida no parâmetro `doc_md`. + + * Ah, aqui você também pode usar *markdown* para + * escrever listas, por exemplo, + * ou colocar [links](graph)! +``` + +Para ver essa documentação, basta clicar o botão "DAG Docs" em qualquer +tela de visualização da DAG no Airflow. + +![Botão "DAG Docs". Captura de tela da documentação de DAG no Airflow.](https://github.com/gestaogovbr/Ro-dou/blob/main/docs/img/exemplo-dag-doc_md.png?raw=true) + +### Exemplo 8 +Esta configuração envia as notificações para canais Discord. É necessário ter +permissões de administrador no Discord para gerar o Webhook: + +```yaml +dag: + id: discord_example + description: Envia notificações para canal Discord + search: + terms: + - manifestação cultural + - expressão cultural + - política cultural + report: + report: + discord: + webhook: https://discord.com/api/webhooks/105220xxxxxx811250/Q-XsfdnoHtudTQ-8A6zzzzznitai-vi0bGLE7xxxxxxxxxxxxxxxxxxxmx94R3oZ1h0ngl1 +``` + +### Exemplo 9 +Esta configuração envia as notificações para canais Slack. É necessário ter +permissões de administrador no Slack para gerar o Webhook: + +```yaml +dag: + id: slack_example + description: Envia notificações para canal Slack + search: + terms: + - manifestação cultural + - expressão cultural + - política cultural + report: + report: + slack: + webhook: https://hooks.slack.com/services/XXXXXXXX/XXXXNFDXXX/n6QXXXXrPwxQ71ZXXXXXT9 +``` + +### Exemplo 10 +Esta configuração filtra os resultados por órgão/unidade selecionados. +Por enquanto disponível apenas para as pesquisas no DOU. + +```yaml +dag: + id: department_example + description: DAG de teste (filtro por departamento) + search: + terms: + - dados abertos + department: + - Ministério da Gestão e da Inovação em Serviços Públicos + - Ministério da Defesa + report: + emails: + - destination@gestao.gov.br + subject: "Teste do Ro-dou" +``` \ No newline at end of file diff --git a/docs/docs/funcionamento.md b/docs/docs/como_funciona/index.md similarity index 100% rename from docs/docs/funcionamento.md rename to docs/docs/como_funciona/index.md diff --git a/docs/docs/como_funciona/operadores.md b/docs/docs/como_funciona/operadores.md new file mode 100644 index 0000000..98f7554 --- /dev/null +++ b/docs/docs/como_funciona/operadores.md @@ -0,0 +1,3 @@ +# Operadores de Pesquisa Avançada + +# TODO \ No newline at end of file diff --git a/docs/docs/como_funciona/parametros.md b/docs/docs/como_funciona/parametros.md new file mode 100644 index 0000000..cc4d7ef --- /dev/null +++ b/docs/docs/como_funciona/parametros.md @@ -0,0 +1,39 @@ +# Parâmetros de pesquisa disponíveis + +A página abaixo lista os parâmetros configuráveis nos arquivos YAML: + +## Parâmetros da DAG +* **id**: o nome identificador da DAG a ser gerada. +* **description**: descrição da DAG de pesquisa. +* **doc_md**: documentação em markdown da DAG para uma descrição mais completa. +* **schedule**: agendamento da periodicidade de execução da DAG. Padrão cron (0 8 * * MON-FRI) +* **tags**: tags para categorizar a DAG. +* **owner**: responsável pela DAG. + +## Parâmetros da Pesquisa (Search) +* **search**: pode ser uma ou uma lista de pesquisas. +- **date**: intervalo de data para busca. Valores: DIA, SEMANA, MES, ANO. Default: DIA +- **department**: lista de unidades a serem filtradas na busca. O nome deve ser idêntico ao da publicação. +- **dou_sections**: lista de seções do DOU onde a busca deverá ser realizada. Valores aceitos: SECAO_1, SECAO_2, SECAO_3, EDICAO_EXTRA, EDICAO_SUPLEMENTAR, TODOS. +- **field**: campos dos quais os termos devem ser pesquisados. Valores: TUDO, TITULO, CONTEUDO. Default: TUDO +- **force_rematch**: indica que a busca deve ser forçada, mesmo que já tenha sido feita anteriormente. Valores: True ou False. +- **full_text**: define se no relatório será exibido o texto completo, ao invés de um resumo. Valores: True ou False. Default: False. +- **ignore_signature_match**: ignora a correspondência de assinatura ao realizar a busca. Valores: True ou False. Default: False. +- **is_exact_search**: busca somente o termo exato. Valores: True ou False. Default: True. +- **sources**: fontes de pesquisa dos diários oficiais. Pode ser uma ou uma lista. Opções disponíveis: DOU, QD, INLABS. +- **terms**: lista de termos a serem buscados. Para o INLABS podem ser utilizados operadores avançados de busca. +- **territory_id**: identificador do id do município. Necessário para buscar no Querido Diário. + +## Parâmetros do Relatório (Report) +- **attach_csv**: Anexar no email o resultado da pesquisa em CSV. +- **discord_webhook**: URL de Webhook para integração com o Discord. +- **emails**: Lista de emails dos destinatários. +- **footer_text**: Texto em HTML do rodapé do relatório. +- **header_text**: Texto em HTML de cabeçalho do relatório. +- **hide_filters**: Omite no relatório os filtros de pesquisa. +- **no_results_found_text**: Texto padrão para quando não há resultados encontrados. Default: Nenhum dos termos pesquisados foi encontrado nesta consulta. +- **report**: parâmetros de notificação de relatório. +- **skip_null**: Dispensa o envio de email quando não há resultados encontrados em todas as pesquisas. Valores: True ou False. Default: True. +- **slack_webhook**: URL de Webhook para integração com o Slack. +- **subject**: Texto de assunto do email. + diff --git a/docs/docs/utilizacao.md b/docs/docs/como_utilizar/instalacao/instalacao.md similarity index 67% rename from docs/docs/utilizacao.md rename to docs/docs/como_utilizar/instalacao/instalacao.md index 32d5e9e..436bbb2 100644 --- a/docs/docs/utilizacao.md +++ b/docs/docs/como_utilizar/instalacao/instalacao.md @@ -1,12 +1,3 @@ -# Como utilizar - -Nesta seção, você encontrará as seguintes informações sobre o Ro-DOU: - -* Instalação e configuração -* Ambiente local e ambiente de produção -* Usuários internos e externos ao Ministério da Gestão e da Inovação em Serviços Públicos -* Notificação de erros na execução das DAGs do Apache Airflow - ## Instalação e configuração ### Configurando o ambiente local 'Hello World' @@ -64,36 +55,4 @@ Uma vez executados esses passos, basta agora inicializar o Ro-DOU por meio do co ```bash make run -``` - -## Usuários internos e externos - -### Usuários do Ministério da Gestão e da Inovação em Serviços Públicos - -Para as unidades do Ministério da Gestão e da Inovação em Serviços Públicos que desejem solicitar a utilização de clippings via Ro-DOU, a Secretaria de Gestão e Inovação do MGI está disponível para auxiliá-las a configurar o serviço. - -É preciso que a unidade interessada encaminhe as seguintes informações para o endereço [seges.cginf@gestao.gov.br](mailto:seges.cginf@gestao.gov.br): - -* texto do assunto do e-mail que conterá o relatório do Ro-DOU; -* lista de termos (palavras-chaves) para a pesquisa, separadas linha a linha; -* seção ou seções do DOU que deverá(ão) ser pesquisada(s); -* horário e dias da semana para realização da pesquisa e envio do relatório (por padrão, ocorre às 9h da manhã, de segunda-feira a sexta-feira); e -* lista com os endereços de e-mail  que receberão o relatório do Ro-DOU. - -### Usuários externos (de fora do MGI) - -Usuários de órgãos públicos que não sejam unidades do Ministério da Gestão e da Inovação em Serviços Públicos poderão enviar dúvidas ou comentários ao endereço [seges.cginf@gestao.gov.br](mailto:seges.cginf@gestao.gov.br). - -## Notificação de erros na execução das DAGs - -É importante recordar que o Ro-DOU permite o envio de mensagens via Slack quando ocorre alguma falha na execução da DAG no Apache Airflow. Para usar essa funcionalidade, efetue as seguintes configurações: - -1. Criar o app no Slack conforme orientações do vídeo [How to Add Slack Notifications to Your Airflow DAG's with Airflow Notifiers](https://www.youtube.com/watch?v=4yQJWnhKEa4&ab_channel=TheDataGuy). - -2. Criar uma conexão no Apache Airflow com a seguinte configuração: - - * `Connection Id` = `slack_notify_rodou_dagrun` - * `Connection Type` = `Slack API` - * `Description` = `{"channel": "nome-do-channel-para-mandar-mensagem"}` - * `Slack API Token` = `obtido no passo 1` - +``` \ No newline at end of file diff --git a/docs/docs/como_utilizar/instalacao/notificacao_de_erros.md b/docs/docs/como_utilizar/instalacao/notificacao_de_erros.md new file mode 100644 index 0000000..166c5ab --- /dev/null +++ b/docs/docs/como_utilizar/instalacao/notificacao_de_erros.md @@ -0,0 +1,12 @@ +## Notificação de erros na execução das DAGs + +É importante recordar que o Ro-DOU permite o envio de mensagens via Slack quando ocorre alguma falha na execução da DAG no Apache Airflow. Para usar essa funcionalidade, efetue as seguintes configurações: + +1. Criar o app no Slack conforme orientações do vídeo [How to Add Slack Notifications to Your Airflow DAG's with Airflow Notifiers](https://www.youtube.com/watch?v=4yQJWnhKEa4&ab_channel=TheDataGuy). + +2. Criar uma conexão no Apache Airflow com a seguinte configuração: + + * `Connection Id` = `slack_notify_rodou_dagrun` + * `Connection Type` = `Slack API` + * `Description` = `{"channel": "nome-do-channel-para-mandar-mensagem"}` + * `Slack API Token` = `obtido no passo 1` diff --git a/docs/docs/como_utilizar/introducao.md b/docs/docs/como_utilizar/introducao.md new file mode 100644 index 0000000..23ce0bd --- /dev/null +++ b/docs/docs/como_utilizar/introducao.md @@ -0,0 +1,8 @@ +# Como utilizar + +Nesta seção, você encontrará as seguintes informações sobre o Ro-DOU: + +* Instalação e configuração +* Ambiente local e ambiente de produção +* Usuários internos e externos ao Ministério da Gestão e da Inovação em Serviços Públicos +* Notificação de erros na execução das DAGs do Apache Airflow \ No newline at end of file diff --git a/docs/docs/como_utilizar/usuarios.md b/docs/docs/como_utilizar/usuarios.md new file mode 100644 index 0000000..5b6b2a1 --- /dev/null +++ b/docs/docs/como_utilizar/usuarios.md @@ -0,0 +1,17 @@ +## Usuários internos e externos + +### Usuários do Ministério da Gestão e da Inovação em Serviços Públicos + +Para as unidades do Ministério da Gestão e da Inovação em Serviços Públicos que desejem solicitar a utilização de clippings via Ro-DOU, a Secretaria de Gestão e Inovação do MGI está disponível para auxiliá-las a configurar o serviço. + +É preciso que a unidade interessada encaminhe as seguintes informações para o endereço [seges.cginf@gestao.gov.br](mailto:seges.cginf@gestao.gov.br): + +* texto do assunto do e-mail que conterá o relatório do Ro-DOU; +* lista de termos (palavras-chaves) para a pesquisa, separadas linha a linha; +* seção ou seções do DOU que deverá(ão) ser pesquisada(s); +* horário e dias da semana para realização da pesquisa e envio do relatório (por padrão, ocorre às 9h da manhã, de segunda-feira a sexta-feira); e +* lista com os endereços de e-mail  que receberão o relatório do Ro-DOU. + +### Usuários externos (de fora do MGI) + +Usuários de órgãos públicos que não sejam unidades do Ministério da Gestão e da Inovação em Serviços Públicos poderão enviar dúvidas ou comentários ao endereço [seges.cginf@gestao.gov.br](mailto:seges.cginf@gestao.gov.br). \ No newline at end of file diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f9ff8f8..74d18ba 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -3,11 +3,22 @@ site_name: Ro-DOU - ferramenta de clipping dos diários oficiais nav: - Página Inicial: index.md - O que é Ro-DOU?: rodou.md - - Como utilizar: utilizacao.md - - Como funciona: funcionamento.md - - Como contribuir: contribuicoes.md - - FAQ: faq.md - - Oficinas e mídias: midias.md + - Como utilizar: + - Introdução: como_utilizar/index.md + - Instalação: + - Instalação: como_utilizar/instalacao/instalacao.md + - Notificação de Erros: como_utilizar/instalacao/notificacao_de_erros.md + - Como funciona: + - Introdução: como_funciona/index.md + - Parâmetros de pesquisa: como_funciona/parametros.md + - Operadores de pesquisa avançada: como_funciona/operadores.md + - Exemplos: como_funciona/exemplos/exemplos.md + - Como contribuir: + - contribuicoes.md + - Oficinas e mídias: + - midias.md + - Outros: + - faq.md - Links relevantes: links.md - Contato: contato.md - Changelog: changelog.md