Melhorias de documentação #881 (#981)

#### Descrição

- Issue #881 
- Adicionei sobre o WSL
- Modifiquei os arquivos de Troubleshooting

docs/CONTRIBUTING-en-US.md

@@ -46,14 +46,25 @@ pre-commit install
 _Attention:_ These steps need to be executed only the first time you interact with the project during the environment setup. After that, just activate the virtual environment (step 3) every time you use or contribute to the repository.
 
 ### Windows
-The following instructions were tried on Windows 10.
-1. [Install Microsoft Visual Build Tools](https://visualstudio.microsoft.com/downloads/). When starting the installation, you need to select `C++ build tools` in the loading tab and also `Windows 10 SDK` and `MSVC v142 - VS 2019 C++ x64/x86 build tools` in the individual components tab.
+#### Using Windows terminal
+The following instructions were tried on Windows 10 and 11. Remember that if you want to integrate with the [querido-diario-data-processing](https://github.com/okfn-brasil/querido-diario- data-processing) it is preferable that your environment configuration is done [using WSL](CONTRIBUTING.md#using-wsl).
+
+1. Install [Visual Studio Community](https://visualstudio.microsoft.com/pt-br/downloads/). Before the installation, you need to select in the **Individual Components** tab "Windows 10 SDK" or "11" (depending on your system) and "MSVC v143 build tools - VS 2022 C++ x64/x86 ( v14.32-17.4)". Note that Windows 10 SDK and MSVC v142 - VS 2019 C++ x64/x86 build tools versions will often be updated, so look for similar items under Individual Components to perform the installation (i.e. newer and compatible with your system). Under **Workloads**, select “Desktop development with C++”. Install the updates, close the application and follow the next steps.
+
 2. Follow all [steps used in Linux](#linux), except for item 3. In it, the command should be:
 ```console
 .venv/Scripts/activate.bat
 ```
 _Note_: In Windows commands, the direction of the slash (`/` or `\`) may vary depending on the use of [WSL](https://learn.microsoft.com/en-us/windows/wsl/about).
 
+#### Using WSL
+
+Open a new Ubuntu terminal and clone the forked [querido-diario](https://github.com/okfn-brasil/querido-diario) repository 
+
+Follow the instructions regarding installation using [Linux](CONTRIBUTING.md#em-linux).
+
+[This tutorial](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/wsl_windows.md) will help you install and configure WSL on your Windows machine.
+
 ## Automated code formatting
 Project uses [Black](https://github.com/psf/black) as an automated tool to format and check code style and [isort](https://github.com/pycqa/isort) to sort the imports. CI will fail if your code are not correctly formatted according these tools.
 

docs/CONTRIBUTING.md

@@ -46,14 +46,27 @@ pre-commit install
 _Atenção:_ Estas etapas precisam ser executadas apenas na primeira vez que interagir com o projeto durante a preparação do ambiente. Depois disso, basta ativar o ambiente virtual (passo 3) cada vez que for utilizar ou contribuir com o repositório.
 
 ### Em Windows
-As instruções a seguir foram experimentadas em Windows 10. 
-1. [Instale o Microsoft Visual Build Tools](https://visualstudio.microsoft.com/downloads/). Ao iniciar a instalação, você precisa selecionar `C++ build tools` na aba de carregamento e também `Windows 10 SDK` e `MSVC v142 - VS 2019 C++ x64/x86 build tools` na aba de componentes individuais.
+
+#### Pelo terminal do Windows
+As instruções a seguir foram experimentadas em Windows 10 e 11. Lembre-se que caso deseje realizar uma integração com o repositório [querido-diario-data-processing](https://github.com/okfn-brasil/querido-diario-data-processing) é preferível que a sua configuração de ambiente seja feita [utilizando WSL](CONTRIBUTING.md#utilizando-wsl).
+
+1. Instale o [Visual Studio Comunidade](https://visualstudio.microsoft.com/pt-br/downloads/) . Ao abrir o terminal do instalado do Visual Studio, antes de instalar, você precisa selecionar na aba de  **Componentes Individuais** "SDK do Windows 10" ou "11" (a depender do seu sistema) e "Ferramentas de build do MSVC v143 - VS 2022 C++ x64/x86 (v14.32-17.4)". Note que muitas vezes as versões Windows 10 SDK e MSVC v142 - VS 2019 C++ x64/x86 build tools serão atualizadas, portanto procure por itens similares em Componentes individuais para realizar a instalação (ou seja, mais novos e compatíveis com o seu sitema). Em **Cargas de Trabalho**, selecione “Desenvolvimento para desktop com C++”. Instale as atualizações, feche o aplicativo e siga os próximos passos.
+
 2. Siga todos os [passos usados no Linux](#em-linux), com exceção do item 3. Nele, o comando deve ser:
 ```console
 .venv/Scripts/activate.bat
 ```
 _Observação_: Nos comandos em Windows, o sentido da barra (`/` ou `\`) pode variar a depender da utilização de [WSL](https://learn.microsoft.com/pt-br/windows/wsl/about).
 
+#### Utilizando WSL
+
+Abra um novo terminal do Ubuntu e faça o clone do repositório forked do [querido-diario](https://github.com/okfn-brasil/querido-diario). 
+
+Siga as instruções referentes À instalação utilizando [Linux](CONTRIBUTING.md#em-linux).
+
+[Este tutorial](https://github.com/Luisa-Coelho/qd-data-processing/blob/readme_update/wsl_windows.md) vai te ajudar na instalação e configuração do WSL na sua máquina Windows.
+
+
 ## Formação automática de código
 O projeto usa [Black](https://github.com/psf/black) como ferramenta de automação para formatar e verificar o estilo do código e usa [isort](https://github.com/pycqa/isort) para organizar as importações. A integração contínua (CI) falhará se seu código não estiver adequadamente formatado. 
 
@@ -62,4 +75,4 @@ Mas, se você seguiu as orientações para configurar o ambiente de desenvolvime
 _Observação_: `make` não é disponibilizado nativamente em Windows, sendo necessário instalá-lo para a utilização sugerida.
 
 # Mantendo
-As pessoas mantenedoras devem seguir as diretrizes do [Guia para Mantenedoras](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#mantendo) do Querido Diário.
+As pessoas mantenedoras devem seguir as diretrizes do [Guia para Mantenedoras](https://github.com/okfn-brasil/querido-diario-comunidade/blob/main/.github/CONTRIBUTING.md#mantendo) do Querido Diário.

docs/README-en-US.md

@@ -1,4 +1,4 @@
-**English (US)** | [Português (BR)](/docs/README.md) 
+**English (US)** | [Português (BR)](/docs/README.md)
 
 <p align="center">
   <a href="https://queridodiario.ok.org.br/sobre" target="_blank"> <img alt="Querido Diário" src="./images/querido-diario-logo.png" width="200">
@@ -115,4 +115,4 @@ All work produced by OKBR is openly and freely available.
 
 # License
 
-Code licensed under the [MIT License](/LICENSE.md).
+Code licensed under the [MIT License](/LICENSE.md).

docs/README.md

@@ -1,4 +1,4 @@
-**Português (BR)** | [English (US)](/docs/README-en-US.md) 
+**Português (BR)** | [English (US)](/docs/README-en-US.md)
 
 <p align="center">
   <a href="https://queridodiario.ok.org.br/sobre" target="_blank"> <img alt="Querido Diário" src="./images/querido-diario-logo.png" width="200">
@@ -133,4 +133,4 @@ Todo o trabalho produzido pela OKBR está disponível livremente.
 
 # Licença
 
-Código licenciado sob a [Licença MIT](LICENSE.md).
+Código licenciado sob a [Licença MIT](LICENSE.md).

docs/TROUBLESHOOTING-en-US.md

@@ -14,4 +14,28 @@ module.c:1:10: fatal error: Python.h: No such file or directory
     error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
 ```
 
-Please try to install `python3-dev`. E.g. via `apt install python3-dev`, if you are using a Debian-like distro, or use your distro manager package. Make sure that you use the correct version (e.g. `python3.6-dev` or `python3.7-dev`). You can check your version via `python3 --version`.
+Please try to install `python3-dev`. E.g. via `apt install python3-dev`, if you are using a Debian-like distro, or use your distro manager package. Make sure that you use the correct version (e.g. `python3.6-dev` or `python3.7-dev`). You can check your version via `python3 --version`.
+
+## Error `pinned with ==`
+
+While running `pip install requeriments`, a inexact pinning error may appear. Therefore, use "--no-deps" along the installation:
+
+~~~Linux
+pip install -r data_collection/requirements-dev.txt --no-deps
+~~~
+
+##  Error `legacy-install`
+
+In your WSL terminal, a `legacy-install failure`, like this one below, may occur while installing packages. 
+
+```
+error: legacy-install failure
+error: command 'x86_64-linux-gnu-gcc' failed: No such file or directory
+```
+
+Thus, upgrade your pio and install some essential libraries for Linux:
+
+~~~Linux
+python3 -m pip install --upgrade pip
+sudo apt-get install build-essential libssl-dev libffi-dev python3-dev
+~~~

docs/TROUBLESHOOTING.md

@@ -13,4 +13,28 @@ module.c:1:10: fatal error: Python.h: No such file or directory
     compilation terminated.
     error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
 ```
-Tente instalar `python3-dev`. Por exemplo, via `apt install python3-dev`, se você está usando uma distro Debian, ou utilize o gerenciamento de pacotes da sua distro (por exemplo, `python3.6-dev` or `python3.7-dev`). Você pode saber qual é a sua versão via `python3 --version`.
+Tente instalar `python3-dev`. Por exemplo, via `apt install python3-dev`, se você está usando uma distro Debian, ou utilize o gerenciamento de pacotes da sua distro (por exemplo, `python3.6-dev` or `python3.7-dev`). Você pode saber qual é a sua versão via `python3 --version`.
+
+## Erro `pinned with ==`
+
+Ao realizar o pip install requeriments pode ocorrer um erro de fixação inexata, então utilize o "--no-deps" ao instalar:
+
+~~~Linux
+pip install -r data_collection/requirements-dev.txt --no-deps
+~~~
+
+##  Erro `legacy-install`
+
+Ao instalar bibliotecas pode ocorrer o seguinte erro no seu terminal WSL:
+
+```
+error: legacy-install failure
+error: command 'x86_64-linux-gnu-gcc' failed: No such file or directory
+```
+
+Então faça o upgrade do pip e instale algumas bibliotecas essenciais do Linux:
+
+~~~Linux
+python3 -m pip install --upgrade pip
+sudo apt-get install build-essential libssl-dev libffi-dev python3-dev
+~~~