Adiciona documentação de frontend e configuração de ponta-a-ponta do …

…QD (#113)

- **Adiciona docs de configuração de ponta-a-ponta**
- **Adiciona docs de design do frontend**

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 <http://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
+        <http://localhost:8080/docs>`_.
+
+7. Como acessar o painel de admin do backend?
+
+    Acesse `0.0.0.0:8000/api/admin <http://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
+        <http://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
+

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

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

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. 

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