diff --git a/docs/pt_BR/source/contribuindo/configuracao-de-ponta-a-ponta.rst b/docs/pt_BR/source/contribuindo/configuracao-de-ponta-a-ponta.rst new file mode 100644 index 00000000..019e39bd --- /dev/null +++ b/docs/pt_BR/source/contribuindo/configuracao-de-ponta-a-ponta.rst @@ -0,0 +1,222 @@ +Configuração de ponta-a-ponta +############################# + +Às vezes é necessário integrar diversas etapas do Querido Diário, principalmente ao +desenvolver soluções no frontend que necessitam de dados que ainda não estão em +produção. + +Como o QD utiliza `podman`_ para gerir sua infraestrutura, orquestrar as etapas +consiste em ajustar variáveis de ambiente e garantir que os containers estão +conseguindo se comunicar. + +.. attention:: + Esta documentação foi testada principalmente em ambientes Linux. Ambientes + Windows WSL ou MacOS podem ter algumas diferenças (contribuições são bem vindas!). + +Começando a configurar pelo processamento de dados +************************************************** + +Como os recursos (banco de dados, motor de busca, etc.) utilizados pelo QD localmente +serão compartilhados por diferentes etapas, o `processamento de dados`_ é um bom +projeto para configurar inicialmente, pois utiliza diversos desses recursos em suas +tarefas de processamento. + +Para configurá-lo, seguiremos o passo-a-passo: + +1. `Instale o podman`_ (caso não esteja instalado); + +2. No Makefile do projeto, mude a variável ``FULL_PROJECT`` para ``true`` (isto faz com + +que portas adicionais sejam abertas pelo pod que será criado); + +3. Execute: + + .. code-block:: bash + + make build + +4. Execute: + + .. code-block:: bash + + make setup + +.. tip:: + Se essa for a primeira vez que está executando o projeto, as variáveis de ambiente + serão criadas no arquivo ``envvars``, na raíz do repositório. Aqui você terá as + credenciais do armazenamento de objetos (Minio), por exemplo. + +.. warning:: + Ao executar o comando ``make setup``, um erro ``bind: address already in use`` pode + + aparecer. Nesse caso, verifique se não tem algum outro serviço no seu computador + utilizando a porta indicada e o pare (ou modifique as variáveis de ambiente e/ou + Makefile, se souber o que está fazendo). + + Caso a porta esteja sendo usada pelo próprio podman por algum erro de execução você + + pode terminar o programa com o comando (usando a porta 8000 de exemplo) ``sudo + kill -9 $(sudo lsof -t -i:8000)``. + + Ao terminar, execute ``make setup`` novamente. + +Agora o pod foi criado, e dentro dele vários recursos como Opensearch, Postgres e Minio + +estão sendo executados. Porém, eles ainda estão "vazios". Vamos populá-los utilizando +o repositório de `raspadores`_. + +Gerando dados com os raspadores +******************************* + +Queremos executar raspadores para popular nosso banco com diários oficiais para serem +processados. Para isso, só precisamos configurar o seguinte: + +1. Copie ``data_collection/local.env`` para ``data_collection/.env``; + +2. Configure o ambiente de desenvolvimento e execute raspadores normalmente, como +indicado em sua documentação. + +Processando os documentos raspados +********************************** + +Agora que temos o armazenamento de objetos e algumas tabelas do banco Postgres +populadas, vamos executar o pipeline principal do processamento de dados para que os +arquivos TXT sejam gerados e o motor de busca seja populado: + +1. Execute no repositório do processamento de dados: + + .. code-block:: bash + + make re-run + +.. note:: + Perceba que o ``make re-run`` está sendo executado aqui e não o ``make run``, pois + o ``make run`` executa o ``make setup``, e se o ``make setup`` for executado, todos + + os recursos serão destruído e reconstruídos novamente, anulando a raspagem que foi + realizada. + +Agora temos arquivos, tabelas e índices populados. Podemos habilitar a API. + +Habilitando a API +***************** + +1. Execute: + + .. code-block:: bash + + make build + +2. Execute: + + .. code-block:: bash + + make re-run + +.. note:: + Pelo mesmo motivo que no processamento de dados, o ``make re-run`` está sendo + executado aqui e não o ``make run``. + +Com a API disponível, podemos iniciar o backend local. + +Habilitando o backend +********************* + +Para lidar com o `Querido Diário: Tecnologias na Educação`_, é necessário configurar o +backend da seguinte forma: + +1. Configure o ambiente de desenvolvimento como indicado na documentação; + +2. Faça o cadastro do superusuário como pedido. + +Com o backend disponível, o frontend que usa API e backend locais também pode ser +configurado. + +Habilitando o frontend +********************** + +Finalmente chegamos na outra ponta da arquitetura do QD! Aqui vamos fazer o seguinte: + +1. Configure o ambiente de desenvolvimento como indicado na documentação; + +2. Aplique esse patch no repositório: + + .. code-block:: bash + + ./src/app/constants.ts + - export const API = 'https://queridodiario.ok.org.br/api'; + + export const API = 'http://localhost:8080'; + + ./src/app/services/utils/index.ts + - export const educationApi = 'https://backend-api.queridodiario.ok.org.br/api/'; + + + export const educationApi = 'http://localhost:8000/api/'; + +Pronto! Agora o ambiente está todo configurado 🎉 + +Dicas de uso do ambiente +************************ + +Algumas maneiras úteis de usar o ambiente de desenvolvimento: + +1. Quer acessar o banco postgres para ver registros de diários oficiais, usuários do +backend, etc.? + + Execute ``make shell-database`` no repositório querido-diario-data-processing e + estará na linha de comando ``psql``. + +2. Quer acessar o motor de busca para ver os índices textuais de diários e excertos +temáticos? + + Execute: + + .. code-block:: bash + + curl -k -u admin:admin -X GET "localhost:9200/_cat/indices?v&pretty=true + + Outros endpoints funcionarão igualmente de acordo com a documentação do opensearch. + +3. Quer acessar o sistema de arquivos para ver onde foram baixados? + + Acesse `localhost:9000 `_ com as credenciais localizadas no + ``envvars`` do repositório querido-diario-data-processing. + +4. Quer baixar mais arquivos de diários e processá-los? + + Execute outro scrapy crawl no repositório querido-diario e então execute ``make + re-run`` no querido-diario-data-processing novamente. + +5. No frontend o live reload está habilitado, mas na API e backend não. Como checar as +mudanças? + + Na API, execute ``make re-run`` novamente. No backend, execute: + + .. code-block:: bash + + python -m cli setup -- pod-name querido-diario + +6. Como acessar a documentação da API? + + Acesse `0.0.0.0:8080/docs <0.0.0.0:8080/docs>`_. + + .. tip:: + Caso ``0.0.0.0`` não funcione, use `localhost:8080/docs + `_. + +7. Como acessar o painel de admin do backend? + + Acesse `0.0.0.0:8000/api/admin `_ com as credenciais + + de superusuário criadas anteriormente. + + .. tip:: + Caso ``0.0.0.0`` não funcione, use `localhost:8000/api/admin + `_. + +.. Referências +.. _podman: https://podman.io/ +.. _processamento de dados: https://github.com/okfn-brasil/querido-diario-data-processing/ +.. _Instale o podman: https://podman.io/docs/installation +.. _raspadores: https://github.com/okfn-brasil/querido-diario/ +.. _Querido Diário\: Tecnologias na Educação: https://queridodiario.ok.org.br/educacao + diff --git a/docs/pt_BR/source/contribuindo/frontend.rst b/docs/pt_BR/source/contribuindo/frontend.rst new file mode 100644 index 00000000..ee2c28b6 --- /dev/null +++ b/docs/pt_BR/source/contribuindo/frontend.rst @@ -0,0 +1,74 @@ +Frontend +######## + +Na :doc:`../entendendo/arquitetura`, o frontend do projeto é a porta de entrada para a +maioria das pessoas conhecerem e usarem o projeto via sua interface web. Contudo, +foi desenvolvido em grandes fases (com lançamento em 2021 e modificações em 2022, com +a adição do `Querido Diário: Tecnologias na Educação`_) e ainda carece de documentação +e de mais especialistas que compreendam o projeto e saibam implementar e avaliar as +melhores práticas. + +Para estruturar o desenvolvimento desta importante parte do projeto de forma +consistente, eficaz e colaborativa, precisamos que todas as pessoas contribuidoras +partam de uma base comum de definições sobre qual é a cara do QD e como ele se +apresenta para o mundo. Vamos iniciar esta conversa a seguir. + +Design system +************* + +O `design system`_ do Querido Diário está sendo desenvolvido seguindo a metodologia de +design atômico. Este documento fornece informações importantes para mantenedores do +projeto, tanto na área de frontend quanto de UI/UX design. Atualmente, estamos focando +na consolidação da base do design system. + +Nesta fase inicial, estamos trabalhando em dois elementos fundamentais: + +Guia de estilos + Definição das diretrizes visuais básicas do projeto. +Mapeamento de componentes (átomos) + Identificação e documentação dos componentes mais básicos da interface. + +Após a consolidação da base, planejamos evoluir para organismos, páginas, etc. Este +processo nos permitirá trabalhar na interface do QD de maneira colaborativa de forma +mais compreensível por todas as pessoas envolvidas. + +Recursos utilizados +=================== + +Para consolidar a base do design system, estamos utilizando: + +* `Manual da marca do Querido Diário`_ +* `Desenho de interfaces do MVP 1 do QD (2021)`_ +* `Desenho de interfaces do MVP 2 do QD (2022)`_ +* `Código existente do frontend`_ + +Estudos de referência +===================== + +Os seguintes estudos foram realizados pela Juliana Holanda Bonomo, embaixadora de +Inovação Cívica da OKBR, e serão utilizados como base para nortear mudanças no projeto: + +`Análise de usabilidade do QD`_ + Este estudo avalia a experiência de uso atual e identifica áreas de melhoria na + interface; +`Estudo de personas do QD`_ + Este estudo fornece insights sobre as pessoas usuárias típicas do Querido Diário, seus + usos e objetivos. + +Notas para pessoas mantenedoras +******************************* + +* Ao desenvolver novos componentes, considere como eles se encaixam na hierarquia + atômica (átomo, molécula, organismo, template ou página); +* Mantenha a documentação atualizada à medida que novos elementos são adicionados ao + design system. + +.. Referências +.. _Querido Diário\: Tecnologias na Educação: https://queridodiario.ok.org.br/educacao +.. _design system: https://www.figma.com/design/anOHB2av9QbYvDDhKCslds/Design-System-QD +.. _Manual da marca do Querido Diário: https://drive.google.com/file/d/14iQYyd8MroNu_9o2_OB8TceCQWfKKKQ5/view?usp=sharing +.. _Desenho de interfaces do MVP 1 do QD (2021): https://drive.google.com/file/d/1mrhc_WEAbtgBpKvrULwY1PTQD9EfNivI/view?usp=drive_link +.. _Desenho de interfaces do MVP 2 do QD (2022): https://drive.google.com/file/d/13NGtCz0t-nxwkYhtvP2I1GipH6C5Ee6F/view?usp=drive_link +.. _Código existente do frontend: https://github.com/okfn-brasil/querido-diario-frontend/blob/main/docs/CONTRIBUTING.md +.. _Análise de usabilidade do QD: https://drive.google.com/file/d/1YuR92YJwLyiOw2ucnqPxrzYy71BoglS_/view +.. _Estudo de personas do QD: https://drive.google.com/file/d/1nPQU3SkN9WuK5YxJTNQUEs-xWj-EZYrP/view diff --git a/docs/pt_BR/source/contribuindo/guia-de-contribuicao.rst b/docs/pt_BR/source/contribuindo/guia-de-contribuicao.rst index 595e4754..05138c2a 100644 --- a/docs/pt_BR/source/contribuindo/guia-de-contribuicao.rst +++ b/docs/pt_BR/source/contribuindo/guia-de-contribuicao.rst @@ -32,7 +32,7 @@ mais afinidade: - Processamento de Dados - https://github.com/okfn-brasil/querido-diario-data-processing - API - https://github.com/okfn-brasil/querido-diario-api - Backend - https://github.com/okfn-brasil/querido-diario-backend -- Frontend - https://github.com/okfn-brasil/querido-diario-frontend +- :doc:`frontend` - https://github.com/okfn-brasil/querido-diario-frontend - :doc:`documentacao` - https://github.com/okfn-brasil/querido-diario-comunidade Descobrindo com o que contribuir diff --git a/docs/pt_BR/source/entendendo/arquitetura.rst b/docs/pt_BR/source/entendendo/arquitetura.rst index 7a764699..a948974b 100644 --- a/docs/pt_BR/source/entendendo/arquitetura.rst +++ b/docs/pt_BR/source/entendendo/arquitetura.rst @@ -98,8 +98,8 @@ realizar operações e entregar os resultados ao *site*. - **Armazenamento em produção**: `PostgreSQL`_ para gestão de usuário e alertas e `Redis`_ para tarefas assíncronas. - **Repositório de código**: https://github.com/okfn-brasil/querido-diario-backend -Frontend -========= +Interface web +============= É o *site* oficial do Querido Diário, sua interface visual para pessoas usuárias via navegação pela *Internet*. Nele, fica a interface de busca de diários oficiais. diff --git a/docs/pt_BR/source/index.rst b/docs/pt_BR/source/index.rst index 8568c7e5..58a70bae 100644 --- a/docs/pt_BR/source/index.rst +++ b/docs/pt_BR/source/index.rst @@ -93,4 +93,6 @@ Para mais informações, consulte os `Termos de Uso e Política de Privacidade`_ contribuindo/guia-de-contribuicao contribuindo/raspadores + contribuindo/frontend contribuindo/documentacao + contribuindo/configuracao-de-ponta-a-ponta