Docker é uma plataforma Open Source que facilita a criação e administração de ambientes isolados (containers). Extraído do https://www.mundodocker.com.br/o-que-e-docker/
Contribua com a página de documentação dos Guardians
Introdução
A página de documentação do Guardians-DSC é um fork do projeto de documentação do openshift. Esse documento é um guia de como contribuir para adicionar e/ou editar alguma informação dessa página. O projeto atualmente utiliza as seguintes tecnologias:
AsciiBinder é um systema de documentação construído no Asciidoctor para a galera que mantém e publica *um monte* de documentos. Tradução livre extraída do http://asciibinder.org/
Você pode checar a sintaxe do AsciiBinder aqui
Após fazer o clone do projeto de documentação do Guardians-DSC, acesse a pasta e execute o comando docker-compose up --build.
Será baixado as imagens docker necessárias para o projeto e o no final o asciidoctor irá aguardar a conexão do livereload.
Após isso, abra seu navegador preferido com a extensão do liverreload instalado, acesse o localhost na porta 8080, navegue
pelos caminhos _preview → main → latest → welcome e ative o livereload para que quando um arquivo .adoc for modificado a página for atualizada automaticamente
sem ter a necessidade de reiniciar os containers.
Figure 1. Asciidoctor esperando conexão do LiveReload
Figure 2. Após ativar o LiveReload
|
Agora que o clone do projeto e a conexão do LiveReload foi feito, você está pronto para contribuir com a documentação do Guardians-DSC! |
Estrutura do projeto
Cada diretório raiz do projeto de documentação do Guardians-DSC pode conter uma coleção de tópicos raiz, e/ou os subdiretórios que está dentro do diretório será um segundo nível do tópico raiz. As exceções para essa regra são diretórios cujo nome começam com um underline ( como _docker, _templates), essas páginas são utilizadas na configuração para montar as páginas de documentação.
Cada diretório raiz (tópico) contém tópicos com arquivos AsciiDoc.
/ /topico_dir1 /subtopico_dir1 /subtopico_dirN /topico_dir/topico1.adoc /topico_dir/topicoN.adoc /topico_dir/subtopico_dir1/topico1.adoc /topico_dir/subtopico_dirN/topicoN.adoc /topico_dir/images /topico_dir/images/img1.png /topico_dir/images/imgN.png ... /topico_dir2
Criando um novo tópico
Tópico e Subtópicos
Na raiz do projeto de documentação crie uma pasta com o nome do assunto em que você queira compartilhar, desta maneira você irá iniciar um novo assunto a ser compartilhado. Caso queira adicionar um subtópico para um assunto já criado, basta adicionar uma pasta dentro da pasta do assunto específico.
Index.adoc
Após criar a pasta ou subpasta é necessário criar um arquivo chamado index.adoc. É a partir desse arquivo que seja gerado a principal página do tópico em que você está criando.
_topic_map.yaml
Certo, nesse momento está quase tudo pronto para que você comece de fato a contribuir para documentação. Antes que você coloque a mão na massa é necessário que você adicione a pasta que
foi criado no arquivo topic_map.yaml. Nesse arquivo é onde o asciibinder vai saber quais tópicos irá converter de .adoc → .html e também em qual ordem será listado os tópicos no menu
a esquerda. Segue um exemplo de entrada válida para o arquivo topic_map.yaml, nesse exemplo criei uma pasta na raiz chamada hello_world
---
Name: Hello World!
Dir: hello_world
Distros: main
Topics:
- Name: Exemplo de contribuição
File: index
Distros: main
Contribua!
A partir de agora você já está apto para começar a editar o arquivo index.adoc que foi criado dentro da pasta nos passos anteriores. Não será mais necessário mais nenhuma configuração, basta escrever o que queira compartilhar que a página será carregada automaticamente (caso o livereload esteja ativado) e a pasta que você fez será adicionado na lista de tópicos no menu a esquerda.
GitHub Pages
As páginas html que são geradas pelo asciibinder não estão adequadas para ser publicadas no GitHub Pages, dessa forma utilizamos a seguinte estratégia: Para cada push realizado na branch master será acionado uma série de etapas que serão executados pelo CircleCI. Essas etapas são:
| 1 | Montar os containers desse projeto. |
| 2 | Montar as páginas html com asciibinder. |
| 3 | Executar scripts de reconfiguração de links e caminhos para ser compatíveis ao GitHub Pages nas páginas html e css. |
| 4 | Realizar push das páginas html modificadas na branch gh-pages. |
Assim, não será necessário se preocupar como e onde a documentação será hospedada, todo o trabalho deve ser feito pelo CircleCI e a hospedagem estará por conta do serviço do GitHub Pages, fazendo com que o repositório do projeto que faz documentação, também a hospede e, também, diminuindo camadas de aprendizagem para que mais pessoas possa contribuir na documentação!
Figure 3. Ciclo de contribuição