Pular para o conteúdo principal

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

Docusaurus​

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 em quatro subspastas:

Docusaurus$ tree docs -d -L 1
    docs
    ├── doc_funcional
    ├── doc_tecnica
    ├── manual
    └── politicas

A pasta manual contém o manual do sistema gerado de forma automática. As pastas doc_funcional e doc_tecnica possuem as documentações que são feitas manualmente. No caso da pasta doc_tecnica, os arquivos Markdown já estão nessa pasta. Já a pasta doc_funcional possui subpastas que classificam o assunto geral que trata cada documentação.

Docusaurus/docs$ tree doc_funcional -L 1 -d
    doc_funcional
    ├── AvaliacaoDesempenho
    ├── CRMeCall
    ├── Devolucao
    ├── EspBrasil
    ├── GestaoAtivos
    ├── GestaoCobrancas
    ├── GestaoCompras
    ├── GestaoContabil
    ├── GestaoContratos
    ├── GestaoEstoque
    ├── GestaoFinancas
    ├── GestaoIndicadores
    ├── GestaoManutencaoAtivos
    ├── GestaoOrcamentaria
    ├── GestaoOrdensServico
    ├── GestaoParceiroNegocio
    ├── GestaoProducao
    ├── GestaoProjetos
    ├── GestaoQualidadeRastreabilidade
    ├── GestaoTributaria
    ├── GestaoVendas
    ├── Integracoes
    ├── Outras
    ├── PortalVendasMarketPlace
    ├── RelatorioExtracaoDados
    ├── Seguranca
    └── TMS

Dentro de cada pasta classificatória da doc_funcional e da doc_tecnica contém um arquivo Indice.md. Após criar um novo arquivo de documentação é necessário criar o link para a documentação no arquivo correto. Por exemplo, se eu criar uma nova documentação técnica, preciso abrir o Indice.md da pasta doc_tecnica e adicionar alí o link para documentação com a descrição do assunto de cada documentação. Segue a abaixo o arquivo de índice da documentação técnica como exemplo:

- [Administração do BrERP: otimizando a performance](AdministracaodoBrERPotimizandoaperformance)
- [Atualizador do Sistema (4.1)](AtualizadordoSistema4.1)
- [Atualizacao do BrERP Web Service Connector - Python](AtualizacaoDoBrERPWSCPython)
- [Atualizacao do BrERP Web Service Connector - PHP](AtualizacaoDoBrERPWSCPHP)
- [Configuração de Horários de Acesso e Restrição](ConfiguracaodeHorariosdeAcessoeRestricao)
- [Configuração de Horários em Restrição de Acesso (4.1)](ConfiguracaodeHorariosemRestricaodeAcesso4.1)
- [Configurador Do Sistema](ConfiguradorDoSistema)
- [Configurando e-mail no BrERP (4.1)](Configurandoe-mailnoBrERP4.1)
- [Criando e Restaurando Backups do Sistema (4.1)](CriandoeRestaurandoBackupsdoSistema4.1)
- [CriaodeInfoWindow](CriaodeInfoWindow)
- [Executando o BrERP como serviço no Linux (4.1)](ExecutandooBrERPcomoserviconoLinux4.1)
- [Executando o BrERP como serviço no Linux](ExecutandooBrERPcomoserviconoLinux)
- [FitNesse](FitNesse)
- [Fitnesse - Testes Automatizados](Fitnesse-TestesAutomatizados)
- [Fluxo de Produção Simplificado (4.1)](FluxodeProducaoSimplificado4.1)
- [FluxosdeTrabalho-AprovacaodeDocumentos (4.1)](FluxosdeTrabalho-AprovacaodeDocumentos4.1)
- [Fluxos de Trabalho - Aprovação de Documentos (4.1)](FluxosdeTrabalho-AprovacaodeDocumentos4.1)
- [Formato de Impressão - Template DOCX](FormatodeImpressao-TemplateDOCX)
- [Gestão de Fluxo de Trabalho no BrERP 4.1](GestaodeFluxodeTrabalhonoBrERP4.1)
- [Gestão de Fluxo de Trabalho no BrERP (4.1)](GestaodeFluxodeTrabalhonoBrERP4.1)
- [Indicador de Atividade](IndicadordeAtividade)
- [Índices PostgreSQL x BrERP](IndicesPostgreSQLxBrERP)
- [Monitor Brerp](MonitorBrerp)
- [Padrões de Desenvolvimento](PadroesdeDesenvolvimento)
- [PostgreSQL: perguntas frequentes](PostgreSQLperguntasfrequentes)
- [Script: Callout](ScriptCallout)
- [Script: Processo](ScriptProcesso)
- [Script: Validação de Login](ScriptValidacaodeLogin)
- [Script: Validação](ScriptValidacao)
- [Testes Funcionais FitNesse](TestesFuncionaisFitNesse)
- [Criando o manual do BrERP e publicando no Docusaurus](documentacao_automatica)
- [Configurando uma conexão com a TecnoSpeed](ConfigurarNFSeRPS)
- [Criação de documentação manual no Portal](documentacao_manual)

Não é necessário indicar a extensão .md, pois o Docusaurus usa apenas o nome sem a extensão para formar a URL de acesso.

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

Docusaurus/website/static$ tree img -d -L 1
    img
    ├── brerpwsc-php
    ├── brerpwsc-python
    ├── docbook_docusaurus
    ├── fitnesse
    ├── icons
    ├── indiceFuncional
    ├── indiceManual
    ├── manual
    ├── NFSeRPS
    └── uploads

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 e/ou espaços nos nomes das pasta. Na nomenclatura da imagem não utilize numerais (escreva por extenso caso seja necessário enumerá-la utilize da seguinte forma ex: createrecordexampleum.png)

Criação e modificação de documentos​

Criação e Modificação pela Máquina Local​

Caso prefira criar e/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:

Docusaurus$ git pull

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

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

Visual Code​

Uma das opções que pode ser utilizado para atualização da documentação é o Visual Code. Para editar clique em Explorer (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 Source Control (Ctrl+Shift+G).
  2. Adicione apenas os arquivos que modificou, clicando no botão mais (+).
  3. Verifique se os documentos adicionados foram para STAGED CHANGES.
  4. Após digite uma mensagem para ser inserida no commit e aperte (Ctrl+Enter).
  5. Por último vá em More Actions (três pontinhos) e clique em Push.

file

Usuários com Sistema Operacional 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.
  • Digite npm install
  • Após no Visual Code, vá no menu terminal, clique em Run Task e selecione o 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 CHANGES, abra o terminal do Git dentro da pasta onde se encontra a imagem e digite: git add nomedaimagem.md, dessa forma será incluído no 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.

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