Criação de documentação manual no Portal
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 indíce 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.
Imagens
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:
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:
Docusaurus$ git clone https://git.devcoffee.com.br/docbook.docusaurus-external
Se você já possui o repositório clonado na sua máquina, é recomendavel 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 reposító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:
- Clique em Source Control (Ctrl+Shift+G).
- Adicione apenas os arquivos que modificou, clicando no botão mais (+).
- Verifique se os documentos adicionados foram para STAGED CHANGES.
- Após digite uma mensagem para ser inserida no commit e aperte (Ctrl+Enter).
- Por último vá em More Actions (três pontinhos) e clique em Push.
Usuários com Sistema Operacional Windows
Ao instalar o Git, configure conforme a imagem abaixo:
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.
- Delete a pasta node_modules que se encontra em Docusaurus\website
- 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á incluido no para o próximo Push.
Atualização
O Portal não é atualizado automaticamente a cada push, mas sim uma vez ao dia às 19h. Sendo assim, uma modificação no repositório só ficará online depois da atualização.
Indexação
A indexação é feita de forma manual rodando um Shell Script que chama um indexador que fica instalado numa máquina local. Devido ao limite de indexação da conta free do Algolia, a indexação é feita uma vez por semana pelo administrador do reposítório