Skip to content

GitLab

autodocAI · Changes

Page history
Update autodocAI authored by Ramicés dos Santos Silva's avatar Ramicés dos Santos Silva
Hide whitespace changes
Inline Side-by-side
autodocAI.md
View page @ 9e87ef51
# Procedimento de Geração de Documentação Automatizada com bito.ai # Automated Documentation Generation Procedure with bito.ai
## Visão Geral ## Overview
Este documento descreve o procedimento para a geração automatizada de documentação utilizando a ferramenta bito.ai, com ênfase no uso de CLI e scripts de automação. A ferramenta permite a criação de documentação técnica de forma eficiente e padronizada, facilitando a manutenção e a atualização contínua dos documentos utilizando Inteligência Artificial Generativa. This document describes the procedure for automated documentation generation using the bito.ai tool, with a focus on using CLI and automation scripts. The tool enables efficient and standardized creation of technical documentation, facilitating the ongoing maintenance and updating of documents using Generative Artificial Intelligence.
## Requisitos ## Requirements
- **bito.ai**: A ferramenta bito.ai deve estar instalada e configurada no ambiente de desenvolvimento. - **bito.ai**: The bito.ai tool must be installed and configured in the development environment.
- **CLI (Command Line Interface)**: O CLI deve estar acessível para execução de comandos. - **CLI (Command Line Interface)**: The CLI must be accessible for executing commands.
- **Scripts de Automação**: Scripts utilizados para automação da geração da documentação. - **Automation Scripts**: Scripts used for automating the documentation generation.
## Instalação e Configuração
### Instalação do bito.ai ## Installation and Configuration
1. **Download e Instalação**: ### Installing bito.ai
- Baixe o instalador apropriado para o seu sistema operacional a partir do site oficial do bito.ai.
- Execute o instalador e siga as instruções na tela para concluir a instalação. 1. **Download and Installation**:
- Para geração da documentação utilizou-se sistema operacional Linux Ubuntu por questões de facilidade no aproveitamento de alguns scripts de automação já disponiblizados pela comunidade. - Download the appropriate installer for your operating system from the official bito.ai website.
2. **Configuração Inicial**: - Run the installer and follow the on-screen instructions to complete the installation.
- Após a instalação, configure o bito.ai com suas credenciais e preferências pessoais. - For documentation generation, a Linux Ubuntu operating system was used due to the ease of utilizing some automation scripts already provided by the community.
- Execute o comando de configuração inicial:
2. **Initial Configuration**:
- After installation, configure bito.ai with your credentials and personal preferences.
- Run the initial configuration command:
```shell ```shell
bito config --setup bito config --setup
``` ```
### Criação das Credenciais do bito.ai ### Creating bito.ai Credentials
1. **Criação de Conta**: 1. **Account Creation**:
- Acesse o site do bito.ai e registre-se para criar uma conta, se ainda não tiver uma. - Visit the bito.ai website and sign up to create an account if you do not have one.
- Complete o processo de registro e verifique seu e-mail para ativar sua conta. - Complete the registration process and check your email to activate your account.
2. **Geração de Chave API**: 2. **Generating an API Key**:
- Faça login no painel de controle do bito.ai. - Log in to the bito.ai control panel.
- Navegue até a seção de **Configurações de API** ou **Credenciais**. - Navigate to the **API Settings** or **Credentials** section.
- Clique em **Criar Nova Chave API**. - Click on **Create New API Key**.
- Defina um nome para a chave e selecione as permissões necessárias. - Provide a name for the key and select the necessary permissions.
- Copie a chave API gerada e guarde-a em um local seguro. Você precisará dessa chave para configurar o CLI. - Copy the generated API key and store it in a secure location. You will need this key to configure the CLI.
3. **Configuração do CLI com a Chave API**: 3. **Configuring the CLI with the API Key**:
- Execute o comando de configuração do CLI com a chave API: - Run the CLI configuration command with the API key:
```bash ```bash
bito configure --auth --api-key YOUR_API_KEY bito configure --auth --api-key YOUR_API_KEY
``` ```
- Substitua `YOUR_API_KEY` pela chave API copiada. - Replace `YOUR_API_KEY` with the copied API key.
## Scripts de Automação ## Automation Scripts
Scripts de automação foram utilizados para geração da documentação em dois cenários diferentes, um deles provendo documentação do código e outro trazendo uma visão geral das funcionalidade encontradas com base nos módulos. A seguir a explicação operacionalização de cada um. Automation scripts were used for documentation generation in two different scenarios: one providing documentation for code and another offering an overview of functionalities based on modules. Below is the explanation of the operation of each.
# Script de Geração Automatizada de Documentação # Automated Documentation Generation Script
## Visão Geral ## Overview
Este script Bash automatiza a criação de documentação para arquivos de código em um diretório específico usando a ferramenta `bito`. Ele gera arquivos de documentação Markdown para scripts com extensões `.sh`, `.py`, `.php` e `.js`, organizando-os em uma estrutura de diretórios correspondente ao diretório de origem. This Bash script automates the creation of documentation for code files in a specific directory using the `bito` tool. It generates Markdown documentation files for scripts with `.sh`, `.py`, `.php`, and `.js` extensions, organizing them into a directory structure corresponding to the source directory.
## Funcionamento do Script ## Script Operation
O script segue os seguintes passos para gerar a documentação: The script follows these steps to generate the documentation:
### 1. Configuração das Variáveis ### 1. Setting Up Variables
O script configura algumas variáveis essenciais: The script sets up some essential variables:
- `BITO_CMD`: Localiza o comando `bito` no sistema. - `BITO_CMD`: Locates the `bito` command in the system.
- `BITO_CMD_VEP`: Define uma opção adicional para o comando `bito`, dependendo da versão. - `BITO_CMD_VEP`: Defines an additional option for the `bito` command, depending on the version.
- `BITO_VERSION`: Obtém a versão atual do `bito` e compara com a versão 3.7 para definir `BITO_CMD_VEP`. - `BITO_VERSION`: Retrieves the current version of `bito` and compares it with version 3.7 to set `BITO_CMD_VEP`.
```bash ```bash
BITO_CMD=`which bito` BITO_CMD=`which bito`
BITO_CMD_VEP="" BITO_CMD_VEP=""
BITO_VERSION=`$BITO_CMD -v | awk '{print $NF}'` BITO_VERSION=`$BITO_CMD -v | awk '{print $NF}'`
# Compare BITO_VERSION to check if its greater than 3.7 # Compare BITO_VERSION to check if it's greater than 3.7
if awk "BEGIN {exit !($BITO_VERSION > 3.7)}"; then if awk "BEGIN {exit !($BITO_VERSION > 3.7)}"; then
BITO_CMD_VEP="--agent create_code_doc" BITO_CMD_VEP="--agent create_code_doc"
fi fi
```
### 2. Verificação de Argumentos ### 2. Verificação de Argumentos
O script verifica se um nome de diretório foi fornecido como argumento de linha de comando. Se não for fornecido, o script exibe uma mensagem de erro e encerra. O script verifica se um nome de diretório foi fornecido como argumento de linha de comando. Se não for fornecido, o script exibe uma mensagem de erro e encerra.
...@@ -86,9 +88,10 @@ if [ $# -eq 0 ]; then ...@@ -86,9 +88,10 @@ if [ $# -eq 0 ]; then
exit 1 exit 1
fi fi
``` ```
### 3. Verificação e Criação de Diretório de Documentação ### 3. Verifying and Creating the Documentation Directory
Verifica se o diretório fornecido existe. Se não existir, exibe uma mensagem de erro e encerra.
Cria um diretório para a documentação, prefixando "doc" ao nome do diretório original. The script checks if the provided directory exists. If it does not exist, it displays an error message and exits.
It creates a documentation directory by prefixing "doc" to the original directory name.
```bash ```bash
folder=$1 folder=$1
...@@ -103,11 +106,10 @@ doc_folder="doc_$(basename $folder)" ...@@ -103,11 +106,10 @@ doc_folder="doc_$(basename $folder)"
if [ ! -d "$doc_folder" ]; then if [ ! -d "$doc_folder" ]; then
mkdir -p "$doc_folder" mkdir -p "$doc_folder"
fi fi
```
### 4. Geração de Documentação ### 4. Generating Documentation
Encontra todos os arquivos com extensões específicas no diretório fornecido e seus subdiretórios.
Para cada arquivo encontrado, cria uma estrutura de diretórios correspondente no diretório de documentação. The script finds all files with specific extensions in the provided directory and its subdirectories. For each file found, it creates a corresponding directory structure in the documentation directory. It generates documentation for each file using the `bito` command and saves the documentation in the appropriate directory.
Gera a documentação para cada arquivo usando o comando bito e salva a documentação no diretório apropriado.
```bash ```bash
find "$folder" -type f -name "*.sh" -o -name "*.py" -o -name "*.php" -o -name "*.js" | while read file; do find "$folder" -type f -name "*.sh" -o -name "*.py" -o -name "*.php" -o -name "*.js" | while read file; do
...@@ -125,23 +127,24 @@ find "$folder" -type f -name "*.sh" -o -name "*.py" -o -name "*.php" -o -name "* ...@@ -125,23 +127,24 @@ find "$folder" -type f -name "*.sh" -o -name "*.py" -o -name "*.php" -o -name "*
# Create documentation using bito and save it in document folder # Create documentation using bito and save it in document folder
file2write="$doc_dir/$(basename "${file%.*}").md" file2write="$doc_dir/$(basename "${file%.*}").md"
echo "Creating documentation in: " $file2write echo "Creating documentation in: " $file2write
# The below command does not work and gives following error # The below command does not work and gives the following error
# Only "-p" flag is applicable for this command. Remove any additional flags and then try again. # Only "-p" flag is applicable for this command. Remove any additional flags and then try again.
# bito -p docprmt.txt -f "$file" >> "$file2write" # bito -p docprmt.txt -f "$file" >> "$file2write"
cat $file | bito -p ./prompts/structured_doc.txt $BITO_CMD_VEP > $file2write cat $file | bito -p ./prompts/structured_doc.txt $BITO_CMD_VEP > $file2write
done done
```
### 5. Finalização ### 5. Finalization
Após gerar a documentação para todos os arquivos, o script exibe uma mensagem indicando onde a documentação foi criada.
After generating documentation for all files, the script displays a message indicating where the documentation has been created.
```bash ```bash
echo "Documentation created in $doc_folder" echo "Documentation created in $doc_folder"
```
*** 6. Uso
Para usar o script, execute o seguinte comando, substituindo <folder_name> pelo nome do diretório que contém os arquivos de código: ### 6. Usage
To use the script, run the following command, replacing `<folder_name>` with the name of the directory that contains the code files:
```bash ```bash
./nome_do_script.sh <folder_name> ./script_name.sh <folder_name>
```