update docs

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:
+      - [email protected]
+```
+
+### 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:
+      - [email protected]
+      - [email protected]
+    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 protected]
+    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 protected]
+    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 protected]
+```
+
+### 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:
+      - [email protected]
+    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:
+      - [email protected]
+    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:
+      - [email protected]
+    subject: "Teste do Ro-dou"
+```

docs/docs/como_funciona/operadores.md

@@ -0,0 +1,3 @@
+# Operadores de Pesquisa Avançada
+
+# TODO

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.
+

docs/docs/utilizacao.md → 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 [[email protected]](mailto:[email protected]):
-
-* 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 [[email protected]](mailto:[email protected]).
-
-## 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`
-
+```

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`

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

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 [[email protected]](mailto:[email protected]):
+
+* 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 [[email protected]](mailto:[email protected]).