Skip to main content

Criando o manual do BrERP com o Docbook Generator e publicando com o Docusaurus

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 e, além disso, criar um portal para centralizar toda a documentação funcional e técnica relacionado ao BrERP.

Para gerar o manual foi utilizado o Docbook Generator. Essa ferramenta foi atualizada para trabalhar com o BrERP 6.2 e também utiliza o Selenium para salvar screenshots das telas do sistema de forma automática durante a criação do manual.

Preparando ambiente para a execução do Docbook Generator​

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

Segue o comando hg com o link para clonar o Docbook:

    hg clone https://alm.devcoffee.com.br/hg/brerp-saas.docbook

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

Passo 1 - 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.

file

Passo 2 - Executar o DocBookGeneratorAplication​

Esse é o passo mais demorado. Aqui o DocBook 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 DocBook. Para contornar isso, foi utilizada uma instrução try-catch que tenta abrir a próxima janela, se o selenium retornar um erro, o Docbook fecha o Firefox e executa uma nova instância para abrir a janela solicitada.

file

Passo 3 - Conversão das páginas dos sistema e de exemplos de dados​

Após os XMLs gerados, convertemos para html as páginas da documentação e as páginas de exemplos de dados. Para isso, executamos o buildhtml.xml e o buildDataExamples.xml como Ant Build.

file file

Passo 4 - Conversão para Markdown e estrutura de pastas do Docusaurus​

Após é necessário executar um shell script. Ele se encontra na pasta "brerp-saas.docbook/docbook/". Ele vai converter o html para markdown e preparar os arquivos para o Docusaurus. Para executar o script abra o terminal, vá até a pasta indicada e execute o seguinte comando:

./html2md.sh

No fim da execução desse script vai ser gerado o arquivo "Docusaurus.tar.gz" na mesma pasta do script. Dentro desse arquivo já está o manual com a estrutura de pastas do Docusaurus.

brerp-saas.docbook/docbook$ ls
book4WebHelp.out.xml  buildDataExamples.xml  buildhtml.xml  buildWeb.xml  docbook-xml-4.5  Docusaurus         ExampleData  html2md.sh  lib     simpleXML
book4WebHelp.xml      buildePub.xml          buildPDF.ant   css           docbook-xsl      Docusaurus.tar.gz  HTML         input       pandoc
brerp-saas.docbook/docbook$

Adicionando o manual no Docusaurus​

O Docusaurus é uma ferramenta para publicação e manutenção de documentação. Ela está no gitea da devCoffee, 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 gitea na máquina, adicioná-los localmente e e fazer um commit para o Docusaurus no gitea.

Passo 1 - Clonando o repositório do Gitea​

O Docusaurus pode ser clonado pelo seguinte comando:

git clone https://gitea.devcoffee.com.br/jonatas.silvestrini/Docusaurus

Lembrando que para poder clonar o Docusaurus é necessário logar ao menos uma vez no gitea 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:

[jonatas@Jonatas 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.

Atenção:​

NUNCA delete essas pastas no Docusarus. O DocBook 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 repostó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 não atualiza automaticamente por enquanto. É necessário entrar em contato com o administrador de rede e solicitar uma atualização do portal publicado realizando um pull no repositório.

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.

Instalando DocSearch (crawler)​

O DocSearch pode ser facilmente instalado seguindo o tutorial do próprio Algolia: https://community.algolia.com/docsearch/run-your-own.html Para instalar, ele já pede uma conta do Algolia para poder configurar o crawler. A devCoffee 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 seram usadas para indexar as páginas. Basta excutar 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.

Criação de índice das Documentações Técnicas e Funcionais herdadas do OpenKB​

Como a devCoffee já possuia um portal de documentação com vários artigos e documentos publicados, surgiu a necessidade de portar tudo para o novo portal. Além disso, houve uma nova classificação da documentação funcional separando por categorias. Para facilitar a criação dos indices, foi criado um Shell Script que percorre os diretórios da documentação técnica e funcional e cria os indices necessários de forma dinâmica. Para executar o Script, basta abrir o diretório raiz do Docusaurus no terminal e digitar:

./createIndex.sh