Documentação da API de OpenBank da Conta Stone

O site com a documentação da nossa API de OpenBank usa Hugo, um framework open-source escrito em Golang para construção de sites estáticos.

O seu funcionamento é simples: a usuária escolhe um tema, insere conteúdo em arquivos de formato markdown, edita um arquivo de configuração .toml para promover customizações e voilà - 🐭🪄 a mágica gopher acontece!

Visão geral do projeto

Repositórios relacionados

Este é o repositório principal do site da documentação e todo o conteúdo deve ser adicionado aqui, mas existem outros três repositórios relacionados ao projeto:

Tema: o tema que utilizamos é baseado no tema Docsy e pode ser encontrado nesse repositório aqui. Temos um fork para que seja possível promovermos alterações diretamente no estilo que não seriam possíveis através do arquivo de configuração. No nosso projeto, ele é consumido e referenciado como um submódulo git.
Site Sandbox: o código-fonte do site no ambiente de sandbox, que é gerado pelo código deste repositório + hugo a cada push na branch master, pode ser encontrado aqui. Importante ressaltar que o ambiente de sandbox é usado como pré-produção, a única diferença entre os dois é que os artigos sinalizados como draft serão publicados em sandbox.
Site Produção: o código-fonte do site, que é gerado pelo código deste repositório + hugo a cada nova tag de release, pode ser encontrado aqui.

Contribuindo

Nomeando arquivos e diretórios

A url do site vai ser baseada no nome dos diretórios que ficam sob o diretório content. Por isso, é importante que:

espaços sejam representados por hífens
acentos e pontuações não sejam utilizados
os nomes sejam simples e representem aquilo que queremos ver na url

Os artigos devem receber o nome _index.pt.md e devem estar dentro de uma pasta com o nome do título.

Imagem de Capa da Home

É possível alterar facilmente a imagem de capa localizada na homepage do site. Para isso, basta inserir em /content/pt/ uma imagem que contenha a palavra background no nome (e.g cover-background.jpg).

Seções da Home

As seções da home podem ser customizadas diretamente em /content/pt/_index.html, usando blocks do tipo feature. Cada seção precisa ter:

Um ícone, que deve ser escolhido em Font Awesome {1}
Um título {2}
Descrição que aparecerá abaixo do título {3}
Um botão de ação, com:
- Endereço para onde o botão levará {4.a} obs: caso o link seja interno, deve ser usado o endereço relativo
- Texto do botão {4.b}

{{% blocks/feature icon="{1}" title="{2}" %}}
<p>{3}</p><br>
<a href="{4.a}" class="btn btn-lg btn-secondary">{4.b}</a>
{{% /blocks/feature %}}

Ordem do conteúdo

Se nenhuma providência for tomada, as seções e posts vão se organizar em ordem alfabética simples. Para impôr uma ordem intencional, é necessário preencher o campo weight do cabeçalho. O primeiro conteúdo que deve aparecer deve ter weight igual a 1, o segundo igual a 2, e assim por diante.

Fluxo de Git

Mensagens de commit, nomes de branches e títulos de Pull Requests devem seguir os padrões informados no Guia de Estilo Git da Stone.

Para facilitar a colaboração, o fluxo de Git abaixo deve ser seguido:

Deploy

A documentação é disponibilizada em dois ambientes: Sandbox e Produção. A atualização desses ambientes ocorre por meio de duas GitHub Actions, uma para cada ambiente. Essas ações rodam o Hugo e alimentam o repositório de interesse (Sandbox ou Produção) do site com as alterações - o que desencadeia a ação de atualização do site, que utiliza o GitHub Pages.

Em Sandbox

Temos a Action que desencadeia uma nova construção do site sempre que a branch master deste repositório é atualizada. Em sandbox, usamos a flag -D para forçar os artigos que têm draft: true no cabeçalho a serem publicados.

Em Produção

Temos a Action que desencadeia uma nova construção do site sempre que geramos uma tag de release neste repositório.

Usando Hugo

Instalando

Windows

Baixe o executável do Hugo Windows 64 bits ou Windows 32 bits (este executável não é um instalador, é necessário fazer a instalação manual)

Descompacte o conteúdo do ZIP para a pasta C:\Hugo\bin (pode ser na pasta que preferir)

Copie o caminho onde está o executável hugo.exe para configurar seu sistema para reconhecer o comando Hugo. Para isso você deve configurar a variável de ambiente PATH seguindo os passos abaixo:

Em Iniciar > Pesquisar, procure e selecione: Sistema (Painel de Controle)

Clique no link Configurações avançadas do sistema.

Clique em Variáveis de Ambiente. Na seção Variáveis do Sistema, localize a variável de ambiente PATH e selecione-a. Clique em Editar. Se a variável de ambiente PATH não existir, clique em Novo.

Na janela Editar Variável de Sistema (ou Nova Variável de Sistema), especifique o valor (C:\hugo\bin\) da variável de ambiente PATH. Clique em OK. Feche todas as janelas restantes clicando em OK.

Reabra o terminal e execute $ hugo version.

Outras formas de instalação podem ser encontradas aqui

Mac OS

Sugerimos que seja usado o Homebrew, mas no próprio site do Hugo há mais instruções (aqui).

Comando para instalar com Homebrew: $ brew install hugo

Linux

Use o package manager da sua distro/de sua preferência, instruções adicionais aqui

Adicionando conteúdo com Hugo instalado

Para criar um novo conteúdo (na prática, vai ser criado um arquivo markdown que vai ser usado para gerar uma nova página html), deve-se digitar o seguinte comando:

$ hugo new content/nome-da-secao/nome-do-artigo/_index.pt.md

Em seguida, editar o arquivo que foi criado e adicionar o conteúdo que desejar após o fim do cabeçalho (sinalizado por ---). O arquivo estará em:

📂stone-api-docs    
└──📂content    
   └──📂nome-da-secao
      └──📂nome-do-artigo
         └──📄_index.pt.md

Cada artigo tem um campo chamado draft no cabeçalho, que pode ter o valor true (caso seja ainda um rascunho) ou false (caso deva ser publicado). O default do campo é true, altere para false para sinalizar que o artigo deve ser publicado no ambiente de Produção. 🚨 Mesmo que o campo draft tenha o valor true, o artigo será publicado no ambiente de Sandbox!

Rodando localmente

Como o projeto necessita de git submodules para o seu funcionamento, você deve os iniciar da seguinte forma:

Caso ainda não tenha clonado o projeto:

$ git clone --recurse-submodules https://github.com/stone-co/stone-api-docs.git

Caso já tenha clonado:

$ git submodule update --init --recursive

⚠️ É importante rodar localmente antes de submeter as suas contribuições para o repositório remoto para poder visualizar o site e verificar se não há erros na sua construção.

Digitar no terminal o seguinte comando:
```
$ hugo server
```
🔍 Obs: se você quiser forçar os drafts a serem publicados, utilize a flag -D
No seu navegador, visitar o endereço localhost:1313 (ou o endereço que for informado no próprio terminal após rodar o comando acima)
Para parar, apertar Ctrl + C no terminal

Para mais informações sobre Hugo: getting started do Hugo e oficina de sites estáticos com hugo.

adrielcafe / stone-api-docs