Skip to main content

Manutenção do Docusaurus

Status: Finalizado ✅

Essa página é dedicada à manutanção dessa documentação. Como o projeto do Obra Play ainda está em desenvolvimento, muita coisa será ajustada/adicionada, e assim, muitas dessas mudanças terão que ser refletidas aqui.

Setup do projeto​

Para conseguir ajustar a documentação é necessário ter alguns programas baixados, ter acesso ao repositório, etc.

Acesso ao repositório​

É necessário ter acesso ao repositório no Github do Obra Play, caso não tenha, solicitar acesso com o Matheus ou o Fernando.

Programas necessários​

Git​

  1. Acessar o link https://git-scm.com/downloads
  2. Clique em 64-bit Git for Windows Setup.
  3. Depois de baixar, abra o instalador
  4. Clique em Next até aparecer o botão Install
  5. Finalizado a instalação

Node.js​

  1. Acessar o site https://nodejs.org/en/
  2. Clique para baixar a versão 16.14.0 LTS
  3. Depois de baixar, abra o instalador
  4. Clique em next até finalizar o instalação
  5. Finalizado a instalação

Yarn​

Essa etapa necessita que o Node.js tenha sido instalado.

  1. Acessar o CMD indo na barra de pesquisa do Windows e digitando Prompt de comando
  2. Digitar o comando npm --global install yarn para instalar o yarn
  3. Para verificar se tudo deu certo, digite o comando yarn --version. Caso apareça uma versão no estilo 1.22.17 é sinal que deu certo a instalação.
  4. Finalizado a instalação

Visual Studio Code​

  1. Acesse o link https://code.visualstudio.com/
  2. Clique em Download for windows
  3. Depois de baixar, abra o instalador
  4. Aceite os termos e depois clique ne Next até apatecer o botão Install
  5. Clique em Insall
  6. Finalizado a instalação

Clonar o projeto​

  1. Abra o Windows Explorer
  2. Vá até o diretório onde deseja clonar o repositório
  3. Copie o caminho desse diretório
  4. Acessar o CMD indo na barra de pesquisa do Windows e digitando Prompt de comando
  5. Digite o comando cd, coloque um barra de espaço e depois copie o caminho do diretório.
  6. Digite o comando git clone https://git-codecommit.us-east-1.amazonaws.com/v1/repos/obraplaydocs. Depois clique em Enter
  7. Agora será necessário baixar as dependências do Docusaurus, então digite o comando yarn no CMD e de Enter

Configurar o SSH do GitHub​

O Docusaurus faz todo o processo de Deploy automaticamente, apenas precisa que a chave SSH esteja configurada no GitHub.

Para saber se já existe uma chave no seu computador abra o Windows Explorer, acesse a pasta do seu usuário e depois a pasta .ssh. Caso essa última pasta não exista, significa que ainda nenhuma chave foi criada.

Então para criar uma nova chave, abra o terminal e digite o comando:

    ssh-keygen -t rsa -b 4096 -C "seuemail@exemplo.com"

O programa irá perguntar onde deseja salvar a chave, deixe em brando apenas clicando Enter.

    Enter file in which to save the key (/home/your_user_name/.ssh/id_rsa):

Em seguida, irá pedir para inserir uma frase de acesso, e novamente, deixe em branco clicando Enter.

    Enter passphrase (empty for no passphrase):
    Enter same passphrase again:

Com a chave criada, adicione-a ao seu GitHub:

  • Acesse novamente a pasta do seu usuário e depois a pasta .ssh. Nessa pasta conterá a chave pública e a privada
  • Abra o arquivo id_rsa.pub com um editor de texto e copie todo o seu conteúdo.
  • Abra o site do GitHub com a sua conta logada
  • Acesse as configurações da conta
  • Clique em SSH and GPG keys
  • Clique em New SSH key
  • Coloque um título e cole no campo key o que foi copiado do id_rsa.pub
  • Clique em Add SSH key

Pronto, a chave foi adicionada. Para confirmar se tudo deu certo rode o comando abaixo:

    ssh -T git@github.com

Rodar o projeto​

Antes de fazer qualquer alteração, é interessante rodar o projeto.

  1. Acesse o CMD indo na barra de pesquisa do Windows e digitando Prompt de comando
  2. Digite o comando cd, barra de espaço e o caminho completo até a pasta do projeto
  3. Caso ainda não tenha baixado as dependências do Docusaurus, digite o comando yarn
  4. Digite o comando yarn start para rodar o projeto
  5. No output irá aparecer a URL que o projeto está rodando

url

Identificar arquivo​

Para identificar qual arquivo corresponde a cada página, basta acessar a página pelo navegador e na URL terá o caminho para o arquivo.

file path

Ajustar texto da documentação​

Primeiro é necessário abrir o projeto no Visual Studio Code.

  1. Abra o Visual Studio Code
  2. Na parte superior esquerda, clique em File, depois em Open Folder
  3. Selecione a pasta onde foi feito a clonegem do repositório

Para acessar os arquivos da documentação abra a pasta docs, caso o arquivo esteja em um agrupamento abra a pasta do seu agrupamento.
Todos esses arquivos de extesão .md são arquivos de markdown, sendo assim, eles são arquivos de texto com caractéres especiais fazendo papel de marcadores. Faça as alterações necessárias no arquivo e depois salve-o, assim o site de teste será atualizado automaticamente.

Criar nova documentação​

Para se criar uma nova página para a documentação, é preciso apenas criar um novo arquivo de extenção .md dentro da pasta de docs. Sempre priorise por categorizar as páginas inserindo-as na pasta que mais se aprocima do seu assunto.

Variáveis de Ambiente​

Para poder fazer o deploy da documentação normalmente, você precisa configurar em sua máquina duas variáveis de ambiente, o GIT_USER e o USE_SSH. Para configurar essas variáveis, digite no campo de pesquisa do seu sistema operacional variáveis de ambiente do sistema e clique em Enter.

Depois, clique em Variáveis de Ambiente.

change url

Você pode escolher adicionar essas variáveis para o usuário ou para o sistema.

Clique em Novo e adicione a variável GIT_USER com seu nome.

change url

Repita os mesmo passos, mas dessa vez configure a variavel USE_SSH com o valor true.

change url

Clique em Ok, e pronto, suas variáveis de ambiente já estão configuradas.

Deploy​

A documentação é hospedada pelo GitHub Pages. Assim, para propagar as mudanças feitas no ambiente local para o Pages é necessário atualizar o repositório do projeto no GitHub com o novo build.

Para mais informações acesse: https://docusaurus.io/docs/deployment#deploying-to-github-pages

Todo o processo de build, commit e push para o GitHub é feita de forma automatica pelo Docusaurus.
No terminal, vá até a pasta do projeto e digite o comando yarn deploy.

Sempre que é dado deploy a URL da doc é alterada e é necessário atualiza-la para docs.obraplay.com.

  1. Vá até o repositório do projeto no Github
  2. Clique em Settings change url
  3. Vá até a sessão do GitHub Pages e depois clique em Check it out here! change url
  4. Em Custom domain, atualize para docs.obraplay.com change url

É sempre importante dar o deploy depois de adicionar uma alteração relevante.