diff --git a/.gitbook.yaml b/.gitbook.yaml deleted file mode 100644 index abffaa67..00000000 --- a/.gitbook.yaml +++ /dev/null @@ -1,4 +0,0 @@ -root: ./docs/ - -structure: - readme: README.md diff --git a/.gitignore b/.gitignore index 5c42013e..da2ef82f 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,9 @@ db/ ### PyCharm ### .idea/ +### GitBook ### +_book/ + # Created by https://www.gitignore.io/api/vim,linux,macos,python ### Linux ### *~ diff --git a/README.md b/README.md index 4aceaf64..fdf99ca6 100644 --- a/README.md +++ b/README.md @@ -74,14 +74,14 @@ conectores, onde ele identifica a *intent*, e responde pelo Rasa Core, de acordo As *models* utilizadas para a conversação foram geradas pelo módulo *trainer* e depois transferidas para o bot, estes modelos podem ser versionados e evoluídos entre bots. Os notebooks avaliam o funcionamento de acordo com o formato das *intents* e *stories*. -O elasticsearch coleta os dados da conversa e armazena para a análise feita pelo kibana, que gera gráficos para +O ElasticSearch coleta os dados da conversa e armazena para a análise feita pelo Kibana, que gera gráficos para avaliação das conversas dos usuários e do boilerplate. ### Bot Este script foi configurado para construir as imagens genéricas necessárias para execução deste ambiente. Caso seu projeto utilize este boilerplate e vá realizar uma integração contínua ou similar, é interessante -criar um repositório para as imagens e substitua os nomes das imagens "lappis/bot", e "lappis/botrequirements" pelas suas respectivas novas imagens, por exemplo "/bot" em repositório público. +criar um repositório para as imagens e substituir os nomes das imagens "lappis/bot", e "lappis/botrequirements" pelas suas respectivas novas imagens, por exemplo "/bot" em repositório público. ### Treinamento @@ -151,6 +151,68 @@ make run-notebooks Acesse o notebook em `localhost:8888` +## Documentação + +A documentação do projeto pode ser executada localmente utilizando o [GitBook](https://www.gitbook.com/). +Para instalar o gitbook via npm, é preciso ter instalado no computador [Node.js e npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). + + +Para conferir a versão do npm: + +```sh +npm -v +``` + +Agora instale o [gitbook](https://til.secretgeek.net/gitbook/use_gitbook_locally.html): + +```sh +npm install -g gitbook +``` + +Agora instale o pacote `cli`: + +```sh +npm install -g gitbook-cli +``` + +Depois de instalado, na pasta raíz do projeto, execute: + +```sh +gitbook build . +``` + +E para rodar localmente execute: + +```sh +gitbook serve . +``` + +E acesse: + +``` +http://localhost:4000/ +``` + +Você também pode rodar o projeto em uma porta diferente: + +```sh +gitbook serve . --port 4003 +``` + + + +#### Observações + +Quando executa o comando `gitbook build .` é criado uma pasta `_book` que contém o arquivo `index.html` e os outros htmls da documentação. Desta forma também é possível visualizar o arquivo `_book/index.html` diretamente em um navegador. + + +Caso na hora de instalar o gitbook a versão do npm estiver desatualizada, você pode atualizar para a [versão mais recente](https://docs.npmjs.com/try-the-latest-stable-version-of-npm) ou uma versão específica. + + +Na raíz do projeto tem o arquivo `SUMMARY.md`, e é importante se atentar a ele pois o que não estiver mapeado nele, não será possível abrir como uma página html no gitbook. + +**Contribuição**: Para contribuir com a documentação do projeto leia [como contribuir para a documentação](docs/Tutoriais/tutorial-como-contribuir-com-documentacao.md) + # Como conseguir ajuda Parte da documentação técnica do framework da Tais está disponível na diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 00000000..511eba2d --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,26 @@ +# Summary + +* [Introdução](README.md) +* [Qualidade do bot](docs/pipeline-de-qualidade.md) + +* [Tutoriais]() + * [Configuração de pipeline de bot](docs/Tutoriais/tutorial-pipeline-de-bot.md) + * [Criação de utter](docs/Tutoriais/tutorial-como-fazer-uma-utter.md) + * [Criação de testes automatizados](docs/Tutoriais/tutorial-testes-automatizados.md) + * [Primeira conversa](docs/Tutoriais/tutorial-primeira-conversa.md) + * [Configuração da Policy do chatbot](docs/Tutoriais/tutorial-como-treinar-o-modelo.md) + * [Criação de visualizações no Kibana](docs/Tutoriais/tutorial-criar-BI.md) + * [Adicionar bot ao RockectChat](docs/Tutoriais/tutorial-add-bot-rocketchat.md) + * [Contribuir com a Documentação](docs/Tutoriais/tutorial-como-contribuir-com-documentacao.md) + +* [Setup]() + * [Setup do bot no Telegram](docs/Setup/setup_telegram.md) + * [Configurando os usuários](docs/Setup/setup_user_elasticsearch.md) + * [Setup Analytics](docs/Setup/setup_analytics.md) + + +# English Summary + +* [English]() + * [Introduction](docs/README-en.md) + diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index dc560c74..00000000 --- a/docs/README.md +++ /dev/null @@ -1,240 +0,0 @@ -# Rasa Boilerplate - - - - -## Tutorial para configurar todo o projeto - -Para ter seu chatbot Rasa no ar e funcionando rápidamente no `shell` execute os seguintes comandos: - -```sh -sudo make build-bot -sudo make train -sudo make run-console -``` - -Estes comandos irão construir o seu chatbot e abrir a conversação no terminal. Tudo está dockerizado -então você não terá problemas de instalação do ambiente. - -## Introdução - -### For English version, see [README-en](docs/README-en.md) - -Um projeto feito em Rasa com configurações necessárias para a construção de um projeto grande de chatbot. - -Este projeto teve como base o projeto [Tais](http://github.com/lappis-unb/tais). - -### Entenda a Arquitetura - -É utilizado no boilerplate diversas tecnologias que interagem entre si para obter um melhor resultado. Veja a arquitetura implementada: - -![](https://user-images.githubusercontent.com/8556291/57933140-d8d66b80-7892-11e9-8d58-a7eda60b099b.png) - -O usuário interage com a Boilerplate via RocketChat ou Telegram, que manda as mensagens para o Rasa NLU através de -conectores, onde ele identifica a *intent*, e responde pelo Rasa Core, de acordo com as *stories* e *actions*. -As *models* utilizadas para a conversação foram geradas pelo módulo *trainer* e depois transferidas para o bot, estes -modelos podem ser versionados e evoluídos entre bots. -Os notebooks avaliam o funcionamento de acordo com o formato das *intents* e *stories*. -O elasticsearch coleta os dados da conversa e armazena para a análise feita pelo kibana, que gera gráficos para -avaliação das conversas dos usuários e do boilerplate. - -### Bot - -Este script foi configurado para construir as imagens genéricas necessárias para execução deste ambiente. -Caso seu projeto utilize este boilerplate e vá realizar uma integração contínua ou similar, é interessante -criar um repositório para as imagens e substitua os nomes das imagens "lappis/bot", e "lappis/botrequirements" pelas suas respectivas novas imagens, por exemplo "/bot" em repositório público. - - -### Treinamento - -**Atenção**: o comando de treinamento é usado para criar os modelos necessários na conversação do bot para treinar o seu chatbot execute o comando: -```sh -sudo make train -``` - -### Console - -```sh -sudo make run-console -``` - -### Telegram - -Após realizar o [tutorial](/docs/setup_telegram.md) de exportação de todas variávies de ambiente necessárias, é possível realizar a execução do bot no telegram corretamente. - -**Antes de seguir adiante. Importante:** As variáveis de ambiente são necessárias para o correto funcionamento do bot, por isso não esqueça de exportá-las. - -Se ainda não tiver treinado seu bot execute antes: - - -Depois execute o bot no telegram: - -```sh -sudo docker-compose up bot_telegram -``` -### Analytics - -Para a visualização dos dados da interação entre o usuário e o chatbot nós utilizamos uma parte da Stack do Elastic, composta pelo ElasticSearch e o Kibana. Com isso, utilizamos um broker para fazer a gerência de mensagens. Então conseguimos adicionar mensagens ao ElasticSearch independente do tipo de mensageiro que estamos utilizando. - -### Configuração do RabbitMQ - -Em primeiro lugar para fazer o setup do analytics é necessário subir o RabiitMQ e suas configurações. - -Inicie o serviço do servidor do RabbitMQ: - -```sh -sudo docker-compose up -d rabbitmq -``` - -Inicie o serviço do consumidor do RabbitMQ, que ficará responsável por enviar as mensagens para o ElasticSearch: - -```sh -sudo docker-compose up -d rabbitmq-consumer -``` - -Lembre-se de configurar as seguintes variáveis de ambiente do serviço `rabbitmq-consumer` no `docker-compose`. - -```sh -ENVIRONMENT_NAME=localhost -BOT_VERSION=last-commit-hash -RABBITMQ_DEFAULT_USER=admin -RABBITMQ_DEFAULT_PASS=admin -``` - -Sendo que as configurações de `RABBITMQ_DEFAULT_USER` e `RABBITMQ_DEFAULT_PASS` devem ser as mesmas definidas no serviço do `rabbitmq`. - -#### Integração com Rasa - -Existem duas formas para executar a Tais com o *broker*. A primeira delas é via linha de comando. -Para utilizar esta forma é preciso definir Dentro do arquivo `endpoints.yml` as configurações do broker: - -```yml -event_broker: - url: rabbitmq - username: admin - password: admin - queue: bot_messages -``` - -Depois basta executar o bot: - -```sh -sudo docker-compose run --rm bot make run-console-broker -``` - -A segunda forma é utilizando o script `run-rocketchat` que é utilizado quando o bot é executado com o RocketChat como canal. Para isso, as mesmas variáveis devem ser configuradas no arquivo `docker/bot/bot.env`. -Lembre-se também de configurar como `True` a seguinte variável do serviço `bot` no arquivo `docker/bot-rocketchat.env`. - -``` -# Broker config -BROKER_URL=rabbitmq -BROKER_USERNAME=admin -BROKER_PASSWORD=admin -QUEUE_NAME=bot_messages -``` - -Ao final é necessário buildar novamente o container do bot. - -``` -sudo docker-compose up --build -d bot -``` - -### Configuração ElasticSearch - -O ElasticSearch é o serviço responsável por armazenar os dados provenientes da interação entre o usuário e o chatbot. - -As mensagens são inseridas no índice do ElasticSearch utilizando o *broker* RabbitMQ. - -Para subir o ambiente do ElasticSearch rode os seguintes comandos: - -``` -sudo docker-compose up -d elasticsearch -sudo docker-compose run --rm -v $PWD/analytics:/analytics bot python /analytics/setup_elastic.py -``` - -Lembre-se de setar as seguintes variaveis de ambiente no `docker-compose`. - -``` -ENVIRONMENT_NAME=localhost -BOT_VERSION=last-commit-hash -``` - -#### Setup Kibana (Visualização) - -Para a análise dos dados das conversas com o usuário, utilize o kibana, e veja como os usuários estão interagindo com o bot, os principais assuntos, média de usuários e outras informações da análise de dados. - -O Kibana nos auxilia com uma interface para criação de visualização para os dados armazenados nos índices do ElasticSearch. - -```sh -sudo docker-compose up -d kibana -``` - -**Atenção:** Caso queira configurar permissões diferentes de usuários (Login) no ElasticSearch/Kibana, siga esse tutorial ([link](https://github.com/lappis-unb/rasa-ptbr-boilerplate/tree/master/docs/setup_user_elasticsearch.md)). - -#### Importação de dashboards - -Caso queira subir com os dashboards que criamos para fazer o monitoramento de bots: - -``` -sudo docker-compose run --rm kibana python3.6 import_dashboards.py -``` - -Após rodar o comando anterior os dashboards importados estarão presentes no menu management/kibana/Saved Objects. - -Você pode acessar o kibana no `locahost:5601` - - - -## Testando Fluxos de Conversa - -É possível testar os fluxos de conversação utilizando o [Evaluation do Rasa Core](https://github.com/lappis-unb/tais/wiki/Testes-Automatizados). Para testá-los no seu bot basta adicionar um arquivo dentro do diretório `bot/e2e/` com as histórias a serem testadas. Essas histórias devem ser descritas normalmente, porém com exemplos de frases para cada uma das *Intents* sendo testadas, segundo o formato abaixo: - -``` -## História de teste 1 -* cumprimentar: oi - - utter_cumprimentar -* action_test: test custom action - - action_test -``` - -Uma vez que os arquivos de teste foram adicionados ao diretório correto, basta rodar os testes com a *task* do bot: - -```sh -sudo docker-compose run --rm bot make test-stories -``` - -Para gerar data-science referente aos testes automatizados de bor, execute o seguinte comando do *Makefile* na raíz do projeto: - -```sh -sudo docker-compose run --rm bot make test-dialogue -``` - -## Notebooks - Análise de dados - -### Setup - -Levante o container `notebooks` - -```sh -docker-compose up -d notebooks -``` - -Acesse o notebook em `localhost:8888` - -# Como conseguir ajuda - -Parte da documentação técnica do framework da Tais está disponível na -[wiki do repositório](https://github.com/lappis-unb/tais/wiki). Caso não encontre sua resposta, abra uma issue -com a tag `duvida` que tentaremos responder o mais rápido possível. - -Em caso de dúvidas em relação ao Rasa, veja o grupo [Telegram Rasa Stack Brasil](https://t.me/RasaBrasil), -estamos lá também para ajudar. - -Veja mais informações de contato em nosso site: https://lappis.rocks - -# Licença - -Todo o framework do boilerplate é desenvolvido sob a licença -[GPL3](https://github.com/lappis-unb/rasa-ptbr-boilerplate/blob/master/LICENSE) - -Veja a lista de dependências de licenças [aqui](https://libraries.io/github/lappis-unb/rasa-ptbr-boilerplate) diff --git a/docs/setup_analytics.md b/docs/Setup/setup_analytics.md similarity index 100% rename from docs/setup_analytics.md rename to docs/Setup/setup_analytics.md diff --git a/docs/Setup/setup_telegram.md b/docs/Setup/setup_telegram.md index 56a47978..fc782479 100644 --- a/docs/Setup/setup_telegram.md +++ b/docs/Setup/setup_telegram.md @@ -1,54 +1,89 @@ -## Setup do bot no Telegram +# Setup do bot no Telegram -##### Crie um bot no Telegram +Para configurar e ter seu bot no telegram, você precisa seguir os seguintes passos: +1. [Criar um bot no telegram com BotFather](#criar-um-bot-no-telegram-com-botfather) +1. [Executar o ngrok](#executar-o-ngrok) +1. [Exportar as variáveis](#exportar-as-variáveis) +1. [Atualizar o arquivo de credenciais](#atualizar-o-arquivo-de-credenciais) -Converse com o [@BotFather do Telegram](https://t.me/BotFather) e crie um bot de teste unicamente seu seguindo as instruções dele. +## Criar um bot no telegram com BotFather +Converse com o [@BotFather do Telegram](https://t.me/BotFather) e crie um bot pra você seguindo as instruções dele. +Você vai sair de lá com duas informações importantes: o `token` e o `username` do seu bot. +Segura elas aí, pois vamos precisar em breve. +## Executar o ngrok -##### Exporte as variáveis do seu bot -Após escolher um nome para seu bot, o @BotFather lhe dará um token para utilizar para acessar a API do Telegram. Adicione ambos no [arquivo de configurações do bot](../docker/bot-telegram.env), como a seguir. Substitua o TELEGRAM_TOKEN pelo token lhe enviado pelo @BotFather e TELEGRAM_BOT_USERNAME pelo nome do seu bot. +Precisamos configurar um webhook para fazer a comunicação do nosso bot com o telegram. +Para isso, vamos utilizar o [ngrok](https://ngrok.com/download). +Nesse link, você vai fazer o download. E executar o comando de unzip do arquivo. + +Faça o download, extraia o arquivo que foi baixado e execute o comando a seguir. ```sh -TELEGRAM_BOT_USERNAME=token_fornecido_pelo_BotFather -TELEGRAM_TOKEN=username_do_bot +./ngrok http 5001 ``` +Esse comando vai executar o ngrok na porta 5001. Ele vai ocupar o terminal em que for executado. + +**Atenção:** O conector do Telegram está utilizando a porta 5001 como padrão. +Caso queira mudar, somente altere a porta utilizada pelo no Makefile. + -##### Execute o ngrok -Após a etapa anterior, é necessário utilizar o [ngrok](https://ngrok.com/download) para expor determinada porta para ser utilizado -pelo Telegram. +## Exportar as variáveis -Conforme a seguir, execute o ngrok na porta 5001. +### Telegram + +Após escolher um nome para seu bot, o @BotFather lhe dará um token para utilizar para acessar a API do Telegram. +Adicione ambos no [arquivo de configurações do bot], como a seguir. +Substitua o `TELEGRAM_TOKEN` pelo token lhe enviado pelo BotFather e `TELEGRAM_BOT_USERNAME` pelo nome do seu bot. ```sh -./ngrok http 5001 +TELEGRAM_BOT_USERNAME=username_do_bot +TELEGRAM_TOKEN=token_fornecido_pelo_BotFather ``` -**Atenção:** O conector do Telegram está utilizando a porta 5001 como padrão. Caso queira mudar, somente altere -a porta utilizada pelo no Makefile. +### NGROK +Enquanto o ngrok estiver em execução, ele apresentará uma série de informações da sessão atual. +Copie a url do campo Forwarding com o protocolo `HTTPS` e cole no [arquivo de configurações do bot]. +Substitua apenas o `your_webhook_server`. Mantenha o restante da linha + +```sh +TELEGRAM_WEBHOOK=your_webhook_server/webhooks/telegram/webhook +``` +> Lembre-se: sempre que executar o ngrok essa url deve ser atualizada. -##### Exporte a URL do Webhook -Enquanto o ngrok estiver em execução, ele apresentará uma série de informações da sessão atual. Copie a url do campo Forwarding com o protocolo HTTPS e cole no [arquivo de configurações do bot](../docker/bot-telegram.env). ela será similar à seguinte. +Ao final de realizar essas configurações, seu [arquivo de configurações do bot] deve estar de acordo com o exibido logo abaixo: ```sh -TELEGRAM_WEBHOOK=link_do_ngrok/webhooks/telegram/webhook +TELEGRAM_BOT_USERNAME= +TELEGRAM_TOKEN= +TELEGRAM_WEBHOOK=/webhooks/telegram/webhook ``` -::Lembre-se::: sempre que executar o ngrok essa url deve ser exportada. +## Atualizar o arquivo de credenciais +Edite o arquivo credentials.yml e descomente as linhas referentes ao telegram: +``` +telegram: + access_token: ${TELEGRAM_TOKEN} + verify: ${TELEGRAM_BOT_USERNAME} + webhook_url: ${TELEGRAM_WEBHOOK} +``` +Não precisa trocar nenhuma informação, apenas descomentar essa seção do arquivo. -##### Execução do bot no telegram -Ao final de realizar essas configurações, seu [arquivo de configurações do bot](../docker/bot-telegram.env) deve estar de acordo com o exibido logo abaixo: +Com isso, é possível realizar a execução do bot com o comando -```sh -TELEGRAM_BOT_USERNAME=lappisbot -TELEGRAM_TOKEN=token -TELEGRAM_WEBHOOK=your_webhook_server/webhooks/telegram/webhook ``` +make run-telegram +``` + +Assim que rodar o comando, você pode conversar com o seu bot no telegram. +Basta procurar ele pelo username que você criou. -Com isso, é possível realizar a execução do bot seguindo os passos do [README](../README.md) +Para mais comandos e informações, veja o [README](https://github.com/lappis-unb/rasa-ptbr-boilerplate/blob/main/README.md) +[arquivo de configurações do bot]: https://github.com/lappis-unb/rasa-ptbr-boilerplate/blob/main/env/bot-telegram.env diff --git a/docs/Tutoriais/setup_user_elasticsearch.md b/docs/Tutoriais/setup_user_elasticsearch.md deleted file mode 100644 index 9b424cf4..00000000 --- a/docs/Tutoriais/setup_user_elasticsearch.md +++ /dev/null @@ -1,74 +0,0 @@ -# Configurando os usuários - -Caso seja desejada a função de se ter usuários com diferentes permissões dentro do kibana, deve-se seguir os seguintes passos (Caso não seja esse seu interesse, pode passar para a próxima sessão): - -OBS: Os seguintes passos podem ser encontrados, com mais detalhes, na seguinte paǵina: https://www.elastic.co/guide/en/elastic-stack-overview/current/get-started-enable-security.html - -**1. Habilitar função de segurança do elastic search:** - - Depois de se subir o container do elastic de acordo com a seção [Setup](https://github.com/lappis-unb/rasa-ptbr-boilerplate/tree/master#setup-elasticsearch), - adicione a seguinte linha ao arquivo 'rasa-ptbr-boilerplate/elasticsearch/elasticsearch.yml': - -``` -xpack.security.enabled: true -``` - -Após adicionar a linha, reinicie o container do Elastic Search - -``` -sudo docker-compose restart elasticsearch -``` - - -**2. Definir senhas para usuários internos do elasticsearch:** - - Entre no container com o comando: - - -``` -sudo docker-compose exec elasticsearch bash -``` - - Dentro do container execute o seguinte comando, preenchendo as senhas que deseja para cada um dos usuários. - - -``` -./bin/elasticsearch-setup-passwords interactive -``` - -**3. Adicionar usuário kibana ao container do kibana** - - Depois de subir o container do kibana de acordo com a seção [Visualização](https://github.com/lappis-unb/rasa-ptbr-boilerplate/tree/master#setup-kibana-visualização), entre no mesmo com o comando: - -``` -sudo docker-compose exec kibana bash -``` - - Dentro do container, execute os seguintes comandos, digitando, quando necessário, o usuário kibana, e a senha criada no passo anterior. - -``` -../bin/kibana-keystore create -../bin/kibana-keystore add elasticsearch.username -../bin/kibana-keystore add elasticsearch.password -``` - -Após executar os comandos acima, reinicie o container do kibana. - -``` -sudo docker-compose restart kibana -``` - - -**4. Crie usuários além do administrador** - - Após os três passos anteriores, será possível entrar no kibana utilizando a conta com usuário 'elastic'. - - Na interface, é possível criar outros usuários, com diversas outras permissões, entrando em ***Management / Security / Users***, e após isso clicando no botão Create New User. - -**5. Definir permissões para usuários.** - - Na criação de usuários é possível se definir permissões para cada um deles, utilizando os ***roles*** definidos pelo elastic. - - Por exemplo, um usuário que deva ter somente aceesso a leitura dos dashboards criados, deverá ter o role ***kibana_dashboard_only_user*** e ***apm_user*** - - É possível criar novos ***roles*** em ***Management / Security / Roles*** diff --git a/docs/add_bot_rocketchat.md b/docs/Tutoriais/tutorial-add-bot-rocketchat.md similarity index 100% rename from docs/add_bot_rocketchat.md rename to docs/Tutoriais/tutorial-add-bot-rocketchat.md diff --git a/docs/Tutoriais/tutorial-como-contribuir-com-documentacao.md b/docs/Tutoriais/tutorial-como-contribuir-com-documentacao.md new file mode 100644 index 00000000..2d798171 --- /dev/null +++ b/docs/Tutoriais/tutorial-como-contribuir-com-documentacao.md @@ -0,0 +1,56 @@ +## Contribuir com a Documentação + +A documentação do projeto utiliza a ferramenta GitBook, e para contribuir com melhorias ou correções primeiro é preciso rodar localmente como mostra no [README](../../README.md). + +Caso tenha alguma dúvida ou queira entender mais a fundo a ferramenta, acesse sua [documentação aqui](https://docs.gitbook.com/). + + +**Estrutura**: São necessários dois arquivos para que o gitbook funcione corretamente. O arquivo *readme* é primeira página da documentação e deve estar na pasta raíz como `./README.md`. +E o arquivo *summary* é o índice da documentação e deve estar também na pasta raíz como `./SUMMARY.md`. + + +O gitbook cria htmls de todos os arquivos markdowns que estejam no `SUMMARY.md`. + +### Primeiros passos + +Então o primeiro passo para contribuir com a documentação é identificar se será uma correção, criação de conteúdo, organização e/ou atualização. +Verifique se já existe uma [issue](https://github.com/lappis-unb/rasa-ptbr-boilerplate/issues) aberta sobre o assunto específico. Caso não tenha, [crie uma issue](https://github.com/lappis-unb/rasa-ptbr-boilerplate/issues/new/choose) e coloque a label de `documentação` e outra caso seja necessário. +Rode localmente o gitbook para ver a documentação do projeto. + +1. Caso a contribuição não precise de criação de novos arquivos, faça as correções nos arquivos e abra um PR descrevendo claramente tudo o que foi feito. + +2. Caso a contribuição envolva exclusão de arquivos, é muito importante verificar o arquivo `summary` e corrigir ou apagar os links que levariam para esses arquivos excluidos. Pois se não tirar desses arquivos, quando abrir vai dar erro. + +3. Se a contribuição envolver atualização de nome de arquivos, é muito importante a correção também do arquivos `summary` e todos os outros que indiquem o redirecionamento, assim como testar antes de abrir o PR. + +4. Se a contribuição envolver criação de novos arquivos, tente seguir o padrão, por exemplo, os tutoriais começam com `tutorial-nome-do-tutorial.md`. Após a criação de um novo arquivo é preciso colocar no arquivo `summary`, onde está o arquivo no projeto. Veja o exemplo do arquivo `./SUMMARY.md`. + + +O arquivo `./SUMMARY.md` segue a seguinte estrutura: + + +```markdown +‌# Summary​ + +## Use títulos para criar grupos de páginas + +* [Introdução](README.md) +* [Setup]() + * [Setup Telegram](docs/Setup/setup-telegram.md) + * [Setup Slack](docs/Setup/slack.md) + +* [Tutorial]() + * [Criar uma intent](docs/Tutoriais/tutorial-criar-intent.md) + * [Como usar slot](docs/Tutoriais/tutorial-usar-slot.md) + +## Segundo grupo de páginas + +* [Introduction](docs/README-en.md) +``` + +Após alterações, rode novamente, verifique o `summary` e teste todos os links. + + +### Referências + +[1] - [https://docs.gitbook.com/integrations/github/content-configuration#structure](https://docs.gitbook.com/integrations/github/content-configuration#structure) diff --git a/docs/setup_telegram.md b/docs/setup_telegram.md deleted file mode 100644 index fc782479..00000000 --- a/docs/setup_telegram.md +++ /dev/null @@ -1,89 +0,0 @@ -# Setup do bot no Telegram - -Para configurar e ter seu bot no telegram, você precisa seguir os seguintes passos: -1. [Criar um bot no telegram com BotFather](#criar-um-bot-no-telegram-com-botfather) -1. [Executar o ngrok](#executar-o-ngrok) -1. [Exportar as variáveis](#exportar-as-variáveis) -1. [Atualizar o arquivo de credenciais](#atualizar-o-arquivo-de-credenciais) - -## Criar um bot no telegram com BotFather - -Converse com o [@BotFather do Telegram](https://t.me/BotFather) e crie um bot pra você seguindo as instruções dele. -Você vai sair de lá com duas informações importantes: o `token` e o `username` do seu bot. -Segura elas aí, pois vamos precisar em breve. - - -## Executar o ngrok - -Precisamos configurar um webhook para fazer a comunicação do nosso bot com o telegram. -Para isso, vamos utilizar o [ngrok](https://ngrok.com/download). -Nesse link, você vai fazer o download. E executar o comando de unzip do arquivo. - -Faça o download, extraia o arquivo que foi baixado e execute o comando a seguir. - -```sh -./ngrok http 5001 -``` -Esse comando vai executar o ngrok na porta 5001. Ele vai ocupar o terminal em que for executado. - -**Atenção:** O conector do Telegram está utilizando a porta 5001 como padrão. -Caso queira mudar, somente altere a porta utilizada pelo no Makefile. - - -## Exportar as variáveis - -### Telegram - -Após escolher um nome para seu bot, o @BotFather lhe dará um token para utilizar para acessar a API do Telegram. -Adicione ambos no [arquivo de configurações do bot], como a seguir. -Substitua o `TELEGRAM_TOKEN` pelo token lhe enviado pelo BotFather e `TELEGRAM_BOT_USERNAME` pelo nome do seu bot. - -```sh -TELEGRAM_BOT_USERNAME=username_do_bot -TELEGRAM_TOKEN=token_fornecido_pelo_BotFather -``` - -### NGROK - -Enquanto o ngrok estiver em execução, ele apresentará uma série de informações da sessão atual. -Copie a url do campo Forwarding com o protocolo `HTTPS` e cole no [arquivo de configurações do bot]. -Substitua apenas o `your_webhook_server`. Mantenha o restante da linha - -```sh -TELEGRAM_WEBHOOK=your_webhook_server/webhooks/telegram/webhook -``` -> Lembre-se: sempre que executar o ngrok essa url deve ser atualizada. - - -Ao final de realizar essas configurações, seu [arquivo de configurações do bot] deve estar de acordo com o exibido logo abaixo: - -```sh -TELEGRAM_BOT_USERNAME= -TELEGRAM_TOKEN= -TELEGRAM_WEBHOOK=/webhooks/telegram/webhook -``` - -## Atualizar o arquivo de credenciais - -Edite o arquivo credentials.yml e descomente as linhas referentes ao telegram: -``` -telegram: - access_token: ${TELEGRAM_TOKEN} - verify: ${TELEGRAM_BOT_USERNAME} - webhook_url: ${TELEGRAM_WEBHOOK} -``` -Não precisa trocar nenhuma informação, apenas descomentar essa seção do arquivo. - - -Com isso, é possível realizar a execução do bot com o comando - -``` -make run-telegram -``` - -Assim que rodar o comando, você pode conversar com o seu bot no telegram. -Basta procurar ele pelo username que você criou. - -Para mais comandos e informações, veja o [README](https://github.com/lappis-unb/rasa-ptbr-boilerplate/blob/main/README.md) - -[arquivo de configurações do bot]: https://github.com/lappis-unb/rasa-ptbr-boilerplate/blob/main/env/bot-telegram.env