Pular para o conteúdo principal

Criação e Publicação da Documentação do BrERP

Este documento detalha os procedimentos para criar, modificar e publicar a documentação do sistema BrERP, tanto manualmente quanto automaticamente.

Documentação Manual​

Esta seção aborda como configurar seu ambiente local para criar e editar a documentação.

Pré-Requisitos​

Para contribuir com a documentação, é necessário ter os seguintes programas instalados em sua máquina:

Obtendo e Atualizando Repositório da Documentação​

O repositório documentacao é o projeto principal com a engine do Docusaurus e todo o conteúdo da documentação. O material criado/alterado deve ser enviado para a branch main, que será automaticamente validada e transportada para a branch gh-pages, sendo onde fica a versão pública.

  1. Abra o terminal;
  2. Navegue até o diretório onde deseja armazenar o projeto;
  3. Clone o repositório da documentação com o comando: 
    git clone git@github.com:devcoffee/documentacao.git
  4. Se você já possui o repositório clonado, certifique-se de que ele está atualizado antes de iniciar o trabalho: 
    git pull

Estrutura de Pastas​

Documentações​

Na pasta raiz da Documentação encontra-se o diretório docs, que contém toda a documentação do projeto, organizada nas seguintes subpastas:

documentacao
└── docs
    ├── dev-guides
    ├── legal-stuff
    ├── release-notes
    ├── system-manual
    │   └── brerp
    │   └── new-features
    └── user-guides
  • system-manual: Armazena os manuais do sistema gerados automaticamente (brerp) e as documentações das funcionalidades lançadas (new-features).
  • dev-guides: os guias para desenvolvedores estão diretamente na pasta.
  • user-guides: os guias para usuários são organizados em subpastas temáticas.
documentacao/docs$ tree user-guides -L 1 -d
user-guides
├── AdministracaoSistema
├── AvaliacaoDesempenho
├── CRMeCall
├── Devolucao
├── GestaoAtivos
├── GestaoCobrancas
├── GestaoCompras
├── GestaoContabil
├── GestaoContratos
├── GestaoEstoque
├── GestaoFinancas
├── GestaoIndicadores
├── GestaoManutencaoAtivos
├── GestaoOrcamentaria
├── GestaoOrdensServico
├── GestaoParceiroNegocio
├── GestaoProducao
├── GestaoProjetos
├── GestaoQualidadeRastreabilidade
├── GestaoTributaria
├── GestaoVendas
├── Integracoes
├── Outras
├── Planilhador
├── PortalVendasMarketPlace
├── Quicklog
├── Seguranca
└── TMS

Cada subpasta em user-guides e dev-guides contém um arquivo _category_.json, que define a ordem e o título da categoria no menu lateral do site.

Imagens​

As imagens devem ser armazenadas em documentacao/static/img. Para manter a organização, crie uma subpasta com o nome da sua documentação e adicione as imagens correspondentes, mantendo o mesmo padrão do diretório documentacao/docs.

Boas Práticas para Imagens
  • Caminho de Referência: Ao referenciar uma imagem em um arquivo Markdown, o caminho deve começar a partir de img/, mesmo que o local físico seja static/img/. Exemplo: 
    ![CreateRecordExample](/img/fitnesse/createrecordexample.png)
  • Nomenclatura: Não utilize acentos, caracteres especiais ou espaços nos nomes de arquivos e pastas. Para nomes compostos, use hífens (-) ou camelCase.

Criando e Enviando Alterações​

Após realizar as modificações nos arquivos, siga os passos abaixo para enviá-las ao repositório.

  1. Adicione os arquivos modificados para a área de "staging":

    git add .

  2. Crie um commit com uma mensagem clara e descritiva sobre a alteração:

    git commit -m "Mensagem do commit"

  3. Envie as alterações para o repositório remoto na branch main:

    git push origin main

Obtendo Dependências e Subindo Localmente​

Para visualizar suas alterações em tempo real antes de publicá-las:

  1. Navegue até a pasta raiz do projeto no terminal;
  2. Instale as dependências (execute este comando apenas na primeira vez ou após atualizações de pacotes): 
    npm instal
  3. Inicie o servidor de desenvolvimento local: 
    npm start
  4. Acesse o site da documentação que estará disponível através do endereço http://localhost:3000.
dica

Se encontrar problemas durante a instalação de dependências, tente remover a pasta node_modules e o arquivo package-lock.json e repita os passos acima.

Visual Studio Code​

O VS Code fornece uma interface gráfica para o Git. Para utilizá-lo:

  1. Abra o Explorador (Ctrl+Shift+E) e na sequência localize, edite e salve os arquivos desejados;
  2. Acesse a aba Controle do Código-Fonte (Ctrl+Shift+G);
  3. Clique no ícone + para preparar os arquivos alterados.
  4. Verifique se os documentos adicionados foram para a área de Alterações Preparadas, conhecido também como a Staging Area;
  5. Digite uma mensagem na caixa de texto para ser inserida no commit e pressione Ctrl+Enter ou clique no ícone de check para confirmar o commit;
  6. Clique nos três pontos .../Mais Ações e clique em Enviar por Push.

Publicação Automática

Todas as alterações enviadas para a branch main são publicadas automaticamente no portal da documentação.

Documentação Automática​

Devido à quantidade de telas e funcionalidades do BrERP, foi desenvolvido um processo para gerar o manual do sistema de forma automática usando a ferramenta BrERP Screenshot, que utiliza o Selenium para capturar imagens das telas.

nota

Antes de trabalhar com a documentação automática, recomendamos que siga os passos do tópico Documentação Manual.

Preparando o Ambiente​

O BrERP Screenshot depende das variáveis de ambiente do BrERP. Portanto, o projeto deve ser clonado para dentro da mesma workspace do Eclipse onde o BrERP está configurado.

Clone o repositório do BrERP Screenshot:

git clone git@github.com:devcoffee/brerp-screenshot.git
Compatibilidade de Versões

Diferenças de versão entre o BrERP e os plugins utilizados pelo BrERP Screenshot podem causar erros. Caso isso ocorra, utilize os plugins do Model.Generator como referência para correções, pois serviram de base para este projeto.

Execução BrERP Screenshot pelo Eclipse​

Uma vez clonado e importado na workspace do Eclipse tanto o Core quanto o BrERP Screenshot, é possível gerar as screenshots do sistema facilmente. Para isso o BrERP deve estar configurado corretamente e o servidor em execução.

Executar o install.app​

É necessário configurar através do install.app os dados da base que será usada para gerar as screenshots.

Preencher Variáveis em Selenium.java​

Abra o arquivo Selenium.java (localizado em src/org/brerp/screenshot/) e ajuste as variáveis de acordo com o seu ambiente local:

  • URL: Endereço de acesso à base do BrERP (ex: http://localhost:6080);
  • user: Nome de usuário para login;
  • userPwd: Senha do usuário;
  • client: Empresa que será utilizado;
  • clientRole: Perfil (Role) que será utilizado;
  • outputDir: Diretório onde as imagens geradas serão salvas.

Executar o server.product.functionaltest​

Para criar as screenshots do sistema, é necessário ter o server.product.functionaltest em execução. Essa é uma versão modificada do server.product para ser usada em testes funcionais utilizando o Selenium.

Executar o ScreenshotGeneratorApplication​

Esse é o passo principal e mais demorado, pois a aplicação iniciará uma instância do Firefox e, utilizando os dados preenchidos no arquivo Selenium.java, fará login no BrERP para capturar as screenshots.

Execução em Segundo Plano (Headless)

Para as screenshots serem obtidas em segundo plano, sem abrir a interface gráfica do navegador, basta descomentar no arquivo Selenium.java a linha com o argumento options.addArguments("--headless");

Caso esteja executando visualmente, o Firefox pode fechar algumas vezes, pois apesar de programar o Selenium para fechar a janela do sistema a cada screenshot, algumas janelas tem comportamentos diferenciados, como pedir para salvar mesmo sem ter alterado nada. Com isso, o Selenium encontra uma operação que não pode ser realizada e quebra a execução do BrERP Screenshot. Para contornar isso, foi utilizada uma instrução try-catch que tenta abrir a próxima janela, se o Selenium retornar um erro, o BrERP Screenshot fecha o Firefox e executa uma nova instância para abrir a janela solicitada.

Gerando as Páginas Markdown do Manual do Sistema​

Caso deseje gerar as documentações novamente, recomendamos que remova os arquivos gerados automaticamente publicados anteriormente, assim evitará de no portal constar documentações de recursos descontinuados.

ATENÇÃO

Na Documentação há arquivos que não são gerados automaticamente. Caso remova os manuais antes de atualizá-los, delete APENAS o conteúdo das pastas:

  • docs/system-manual/brerp/*
  • website/static/img/system-manual/brerp/*

Obtendo o idempiere-stuff​

Conforme abordado no tópico Estrutura de Pastas, os arquivos Markdown presentes no diretório docs/system-manual/brerp/ são gerados automaticamente. Para isso utilizamos o repositório idempiere-stuff, que poderá ser clonado com o comando abaixo:

git clone git@github.com:devcoffee/idempiere-stuff.git

Configurando o config.env​

Na raiz do idempiere-stuff há um arquivo config.env.template, utilize esse arquivo como base para gerar um arquivo no mesmo diretório nomeado config.env. Neste arquivo deverá preencher os dados de acesso ao BD que será percorrido para gerar os arquivos:

  • PGHOST=endereço do servidor
  • PGPORT=porta (normalmente não é alterado)
  • PGDATABASE=nome do BD
  • PGSCHEMA=nome do esquema (normalmente não é alterado)
  • PGUSER=usuário (normalmente não é alterado)
  • PGPASSWORD=senha do usuário (normalmente não é alterado)

Executando o Script executeall.sh​

  1. Verifique se as imagens das screenshots geradas no passo Execução BrERP Screenshot pelo Eclipse estão no diretório idempiere-stuff/genwikipages/img/.
  2. Navegue até o diretório idempiere-stuff/genwikipages e execute o script executeall.sh:

Atualizando o Manual no Repositório​

Após a geração automática, as imagens e os arquivos de documentação precisam ser enviados para o repositório.

nota

Para execução ser bem-sucedida é necessário que no servidos do banco de dados estejam instaladas as extensões unaccent e plpython3u.

Uma vez com o manual atualizado, basta fazer um commit e um push para o repositório. É interessante realizar um pull no repositório antes, pois documentações funcionais e técnicas podem ter sido alteradas ou criadas.

# 1. Garanta que seu repositório local está atualizado
git pull

# 2. Adicione todos os arquivos novos e modificados
git add .

# 3. Crie um commit descritivo
git commit -m "Atualiza manual do sistema via geração automática"

# 4. Envie para a branch principal
git push origin main
nota

São publicadas para o portal automaticamente as alterações realizadas na branch main.

Indexação das páginas no Algolia​

Utilizamos o Algolia como motor de busca para a documentação. A indexação, que permite que o conteúdo seja encontrado pela barra de pesquisa, ocorre automaticamente uma vez por semana. Também pode ser acionada manualmente através do painel do Crawler do Algolia.

Instalação do Crawler (Opcional)​

Para ter controle total sobre o processo de indexação, é possível instalar o crawler do DocSearch localmente via Docker, seguindo o tutorial do próprio Algolia.

nota

Para instalar e configurar o crawler, é necessário possuir uma conta do Algolia. As credenciais de acesso à conta do Algolia da dev&Co podem ser solicitadas ao administrador do repositório.

Geração do Arquivo de Configuração​

O crawler do Algolia precisa de um arquivo JSON que mapeia as URLs e os seletores de conteúdo a serem indexados.

  1. Execute o script createJsonDocSearch.sh na raiz da Documentação: 
    ./createJsonDocSearch.sh
  2. Esse script vai percorrer as páginas do Documentação e gerar o arquivo genConf.json na raiz do projeto.
Importante

O script gera o arquivo de configuração apontando para o domínio de produção documentacao.devcoffee.com.br. Antes de iniciar uma indexação manual, certifique-se de que todas as suas alterações já foram publicadas e estão disponíveis no portal.