Pular para o conteúdo principal

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

Documentação Manual​

Pré-Requisitos​

Para criar ou editar a documentação na sua própria máquina, indicamos que faça o download e instalação os seguintes programas:

Obtendo e Atualizando Repositório​

Abra o terminal e navegue até o diretório onde deseja manter o repositório. Em seguida obtenha o repositório com o seguinte comando:

git clone git@github.com:devcoffee/documentacao.git

Caso já tenha o repositório localmente, atualize-o com:

git pull

Estrutura de Pastas​

Documentações​

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

Docusaurus$ tree docs -d -L 1
├───dev-guides
├───legal-stuff
├───release-notes
├───system-manual
└───user-guides
  • A pasta system-manual armazena os manuais do sistema gerados automaticamente, além das documentações das funcionalidades lançadas no core do BrERP.
  • As pastas user-guides e dev-guides possuem as documentações que criadas manualmente.
    • Em dev-guides, os arquivos Markdown estão diretamente nesta pasta.
    • Em user-guides, os arquivos estão organizados em subpastas temáticas conforme o conteúdo.
Docusaurus/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
    │   └───CTe
    ├───Integracoes
    │   ├───CDI
    │   │   └───AW
    │   └───WhatsApp
    ├───Outras
    ├───Planilhador
    ├───PortalVendasMarketPlace
    ├───Quicklog
    ├───Seguranca
    └───TMS

Cada pasta da user-guides e dev-guides contém um arquivo _category_.json, responsável por definir a estrutura de navegação e exibição no menu lateral do site gerado pelo Docusaurus.

Imagens​

As imagens utilizadas na documentação ficam em /static/img.

Para melhor organização, recomenda-se criar uma subpasta com o nome da documentação dentro de img e armazenar nela todas as imagens correspondentes.

atenção
  • Apesar das imagens ficarem na pasta website/static/img/, o Docusaurus precisa que passe a URL apenas a partir da pasta img. Exemplo:
![CreateRecordExample](/img/fitnesse/createrecordexample.png)
  • Não usar acentuação ou espaços nos nomes dos arquivos/pastas.

Editando e Subindo Alterações​

Faça suas alterações no editor de sua escolha. Depois, utilize os comandos abaixo para enviar ao repositório:

git add .
git commit -m "Mensagem do commit"
git push -u origin master

Obtendo Dependências e Subindo Localmente​

  • Exclua a pasta node_modules se existir;
  • Abra o terminal e execute npm install para instalar todos os pacotes/dependências necessárias para o projeto ;
  • Ainda no terminal, execute npm start para abrir a documentação localmente.

Visual Studio Code​

Uma das opções que pode ser utilizado para atualização da documentação é o Visual Studio Code. Para utilizá-lo:

  1. Abra o Explorador (Ctrl+Shift+E), encontre o arquivo que deseja, faça as alterações necessárias e salve o arquivo;
  2. Clique em Controle do Código-Fonte (Ctrl+Shift+G);
  3. Para Preparar os os arquivos alterados, clique no botão mais (+);
  4. Verifique se os documentos adicionados foram para Alterações Preparadas;
  5. Após digite uma mensagem para ser inserida no commit e aperte (Ctrl+Enter);
  6. Por último vá em Mais Ações (três pontinhos) e clique em Enviar por Push.

Documentação Automática​

Devido a quantidade de telas e funcionalidades do BrERP, se viu a necessidade de criar um método de automático de gerar o manual do sistema. Para gerar o manual, foi criado o BrERP Screenshot para trabalhar com o BrERP e juntamente com o Selenium, salvando screenshots das telas do sistema de forma automática.

Preparando ambiente para a execução do BrERP Screenshot​

O BrERP Screenshot utiliza as variáveis de ambiente do BrERP, por isso ele precisar estar na mesma workspace que o BrERP. Atenção: versões diferentes do sistema podem acarretar em erros de compatibilidade dos plugins utilizados pelo BrERP Screenshot. Se isso ocorrer, utilize os plugins do Model.Generator como guia para corrigir, pois o BrERP Screenshot foi baseado neste.

Segue o comando hg com o link para clonar o BrERP Screenshot:

    git clone git@github.com:devcoffee/brerp-screenshot.git

Execução passo a passo pelo Eclipse​

Uma vez clonado e importado na workspace do BrERP, é possível gerar a documentação facilmente executando o Dockbook e os scripts ant. Lembrando que para isso o BrERP deve estar configurado corretamente e o servidor em execução

Executar o server.product.functionaltest​

Para criar as screenshots do sistemas, é 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 DocBookGeneratorAplication​

Esse é o passo mais demorado. Aqui o BrERP Screenshot vai gerar a documentação em XML e as screenshots do sistema. Abrirá uma sessão do Firefox e será feito o login no BrERP do workspace. O Firefox pode fechar algumas vezes. Isso é normal, 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.

Adicionando o manual no Docusaurus​

O Docusaurus é uma ferramenta para publicação e manutenção de documentação. Ela está no GitHub da dev&Co., o que permite adição e edição de arquivos markdown de forma simples e com muitos recursos. Porém, como o manual possui muitos arquivos (na primeira versão, 1899 arquivos para ser mais preciso) é recomendável clonar o repositório do GitHub na máquina, adicioná-los localmente e e fazer um commit para o Docusaurus no GitHub.

Passo 1 - Clonando o repositório do GitHub​

O Docusaurus pode ser clonado pelo seguinte comando:

git clone https://gitea.devcoffee.com.br/usuario/Docusaurus

Lembrando que para poder clonar o Docusaurus é necessário logar ao menos uma vez no GitHub e solicitar ao administrador do repositório permissão de acesso.

Passo 2 - Descompactando o manual na pasta do Docusaurus​

Após clonar o Docusaurus deve se obter um diretório com o seguinte conteúdo:

[usuario@Usuario Docusaurus]$ tree -L 1
.
├── createIndex.sh
├── createJsonDocSearch.sh
├── docker-compose.yml
├── Dockerfile
├── docs
├── genConf.json
├── OpenKB_files_cópia
└── website

3 directories, 5 files

O arquivo compactado gerado pelo script html2md.sh possuí os dois diretórios listados a cima: docs e website. Basta descompactar e pedir para sobrescrever os arquivos. O próprio git já vai reconhecer que os arquivos foram alterados.

perigo

NUNCA delete essas pastas no Docusarus. O BrERP Screenshot gera apenas o manual do BrERP. No Docusaurus possui outras documentações e informações que não são geradas automaticamente. Se for necessário apagar o manual antes de atualizá-lo delete apenas o conteúdo das pastas docs/manual e website/static/img/manual

Passo 3 - Adicionando as alterações no Git e subindo no repositório​

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.

git pull
git add .
git commit -m "Manual do BrERP X.X, gerado XX/XX/XXXX"
git push -u origin master

O portal atualiza automaticamente as alterações realizadas na main.

Indexação das páginas no Algolia​

O Algolia é a search engine utilizada pelo Docusaurus. Ela indexa as páginas buscando os termos de pesquisa dentro de tags que utilizam CSS. É possível instalar o DocSearch (crawler) da Algolia localmente através de um docker. Assim, temos total controle de quando pode ser feito uma indexação. Com a implementação da pesquisa utilizando o Docsearch do Algolia, a indexação agora ocorre automaticamente uma vez a cada semana, mas pode ser executada de forma manual pelo Crawler do Algolia

Instalando DocSearch (crawler)​

O DocSearch pode ser facilmente instalado seguindo o tutorial do próprio Algolia. Para instalar, ele já pede uma conta do Algolia para poder configurar o crawler. A dev&Co. já possui uma conta. Por favor, entrar em contato com o administrador do repositório para obter mais informações.

Criando o JSON de configuração do Algolia​

Como pode ser observado no tutorial do Algolia, é necessário criar um JSON com as URLs das páginas que e as tags que serão usadas para indexar as páginas. Basta executar o Shell Script createJsonDocSearch.sh que se encontra na pasta raiz do Docusaurus. Esse script vai percorrer as páginas do Docusaurus e montar o JSON do Algolia automaticamente.

./createJsonDocSearch.sh

Com isso será criado o arquivo genConf.json no próprio diretório raiz do Docusaurus. Atenção: O JSON já vai ser criado apontando para o documentacao.devcoffee.com.br Antes de mandar indexar, tenha certeza que o portal publicado é o mais atualizado.