Pular para o conteúdo principal

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

Documentação Manual​

Estrutura de Pastas​

Documentações​

Na pasta raiz do Docusaurus é possível encontrar a pasta docs. Nessa pasta contém toda a documentação e ela está classificada nas seguintes subpastas:

Docusaurus$ tree docs -d -L 1
├───dev-guides
├───legal-stuff
├───release-notes
├───system-manual
└───user-guides

A pasta system-manual contém os manuais do sistema gerados de forma automática e as documentações das Funcionalidades lançadas no core do BrERP. As pastas user-guides e dev-guides possuem as documentações que são feitas manualmente. No caso da pasta dev-guides, os arquivos Markdown já estão nessa pasta. Já na pasta user-guides possui subpastas que classificam o assunto geral que trata cada documentação.

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

Dentro de cada pasta classificatória da user-guides e da dev-guides contém o arquivo _category_.json que é responsável por organizar e estruturar a navegação da documentação. Ele é usado para definir como as pastas e os arquivos Markdown dentro delas serão exibidos no menu lateral do site.

Imagens​

Assim como a documentação as imagens tem uma estrutura de pasta própria. As imagens ficam na pasta /static/img.

Recomenda-se criar uma pasta nova na pasta img e nomeá-la com nome da documentação que você vai criar e salvar as imagens de cada documentação na sua própria pasta. Assim teremos uma melhor organização sobre o conteúdo de cada pasta. Entretanto é preciso tomar cuidado ao apresentar a imagem na documentação. Apesar das imagens ficarem na pasta website/static/img/, o Docusaurus precisa que passe a URL apenas a partir da pasta img. Por exemplo, para indicar uma imagem da documentação Testes Funcionais no BrERP com FitNesse é necessário passar essa URL:

![CreateRecordExample](/img/fitnesse/createrecordexample.png)

Atenção: Não usar letras maiúsculas, acentuação ou espaços nos nomes das pastas.

Criação e Modificação de Documentos​

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

Com o terminal do Git aberto, basta clonar o repositório com o seguinte comando:

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

Se você já possui o repositório clonado na sua máquina, é recomendável obter a versão mais recente antes de fazer qualquer modificação com o seguinte comando:

git pull

Após você poderá criar e editar a documentação com o editor de sua preferência. Ao finalizar as modificações, basta commitar e realizar o push para o repositório:

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

Visual Studio Code​

Uma das opções que pode ser utilizado para atualização da documentação é o Visual Studio Code. Para editar clique em Explorador (Ctrl+Shift+E), encontre o arquivo que deseja, faça as alterações necessárias, salve o arquivo e siga as instruções abaixo:

  1. Clique em Controle do Código-Fonte (Ctrl+Shift+G).
  2. Adicione apenas os arquivos que modificou, clicando no botão mais (+).
  3. Verifique se os documentos adicionados foram para Alterações Preparadas.
  4. Após digite uma mensagem para ser inserida no commit e aperte (Ctrl+Enter).
  5. Por último vá em Mais Ações (três pontinhos) e clique em Enviar por Push.

file

Git no Windows​

Ao instalar o Git, configure conforme a imagem abaixo: file

Após a instalação, vá até o local onde gostaria de salvar o repositório, clique com o botão direito e escolha a opção Git Bash Here para clonar o repositório.

  • Caso exista na raiz do projeto a pasta node_modules, realize sua exclusão;
  • Segure (Shift + botão direito) e abra o PowerShell;
  • Execute o comando npm install;
  • Após isso, no Visual Studio Code, vá no terminal e execute npm start, assim irá abrir localmente o site.

Para adicionar imagens, coloque diretamente na pasta desejada, caso não apareça para ser adicionado em ALTERAÇÕES, abra o terminal do Git dentro da pasta onde se encontra a imagem e digite: git add nomedaimagem.md, dessa forma será incluído para o próximo Push.

Atualização​

Para atualizar o portal, basta realizar o push que a modificação feita no repositório ficará online logo após o deploy.

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 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 BrERP Screenshot. Essa ferramenta foi atualizada para trabalhar com o BrERP 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 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:

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

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

Atenção:​

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.