Contribua com a página de documentação dos Guardians
Introdução
A página de documentação do Física Moderna é 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:
Após fazer o clone do projeto de documentação do Física Moderna, 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 endereço
http://localhost:8080/fisicamoderna/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 Física Moderna! |
Estrutura do projeto
Cada diretório raiz do projeto de documentação do Física Moderna 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.