Procedimento de Geração de Documentação Automatizada com bito.ai

Visão Geral

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.

Requisitos

• bito.ai: A ferramenta bito.ai deve estar instalada e configurada no ambiente de desenvolvimento.
• CLI (Command Line Interface): O CLI deve estar acessível para execução de comandos.
• Scripts de Automação: Scripts utilizados para automação da geração da documentação.

Instalação e Configuração

Instalação do bito.ai

1. Download e Instalação:
   • 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.
   • 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.
2. Configuração Inicial:

   • Após a instalação, configure o bito.ai com suas credenciais e preferências pessoais.

   • Execute o comando de configuração inicial:

     bito config --setup

Criação das Credenciais do bito.ai

1. Criação de Conta:

   • Acesse o site do bito.ai e registre-se para criar uma conta, se ainda não tiver uma.
   • Complete o processo de registro e verifique seu e-mail para ativar sua conta.

2. Geração de Chave API:

   • Faça login no painel de controle do bito.ai.
   • Navegue até a seção de Configurações de API ou Credenciais.
   • Clique em Criar Nova Chave API.
   • Defina um nome para a chave e selecione as permissões necessárias.
   • Copie a chave API gerada e guarde-a em um local seguro. Você precisará dessa chave para configurar o CLI.

3. Configuração do CLI com a Chave API:

   • Execute o comando de configuração do CLI com a chave API:

     bito configure --auth --api-key YOUR_API_KEY

   • Substitua YOUR_API_KEY pela chave API copiada.

Scripts de Automação

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.

Script de Geração Automatizada de Documentação

Visão Geral

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.

Funcionamento do Script

O script segue os seguintes passos para gerar a documentação:

1. Configuração das Variáveis

O script configura algumas variáveis essenciais:

• BITO_CMD: Localiza o comando bito no sistema.
• BITO_CMD_VEP: Define uma opção adicional para o comando bito, dependendo da versão.
• BITO_VERSION: Obtém a versão atual do bito e compara com a versão 3.7 para definir BITO_CMD_VEP.

BITO_CMD=`which bito`
BITO_CMD_VEP=""
BITO_VERSION=`$BITO_CMD -v | awk '{print $NF}'`
# Compare BITO_VERSION to check if its greater than 3.7
if awk "BEGIN {exit !($BITO_VERSION > 3.7)}"; then
    BITO_CMD_VEP="--agent create_code_doc"
fi

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.

if [ $# -eq 0 ]; then
    echo "Please provide folder name as command line argument"
    exit 1
fi

3. Verificação e Criação de Diretório de Documentação

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.

folder=$1

if [ ! -d "$folder" ]; then
    echo "Folder $folder does not exist"
    exit 1
fi

doc_folder="doc_$(basename $folder)"

if [ ! -d "$doc_folder" ]; then
    mkdir -p "$doc_folder"
fi

4. Geração de Documentação

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. Gera a documentação para cada arquivo usando o comando bito e salva a documentação no diretório apropriado.

find "$folder" -type f -name "*.sh" -o -name "*.py" -o -name "*.php" -o -name "*.js" | while read file; do
    # Get relative path of file from folder
    rel_path="${file#$folder/}"

    # Get directory path of file in document folder
    doc_dir="$doc_folder/$(dirname "$rel_path")"

    # Create directory if it does not exist
    if [ ! -d "$doc_dir" ]; then
        mkdir -p "$doc_dir"
    fi

    # Create documentation using bito and save it in document folder
    file2write="$doc_dir/$(basename "${file%.*}").md"
    echo "Creating documentation in: " $file2write
    # The below command does not work and gives following error
    # Only "-p" flag is applicable for this command. Remove any additional flags and then try again.
    # bito -p docprmt.txt -f "$file" >> "$file2write"
    cat $file | bito -p ./prompts/structured_doc.txt $BITO_CMD_VEP > $file2write
done

5. Finalização

Após gerar a documentação para todos os arquivos, o script exibe uma mensagem indicando onde a documentação foi criada.

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:

./nome_do_script.sh <folder_name>