Contribuindo com a documentação do ASP.NET 5 – // Rodolfo Fadino
rodolfo in ASP.NET | November 22, 2015 Contribuindo com a documentação do ASP.NET 5
O ASP.NET 5 é um projeto open source e cross-plataform, todo seu desenvolvimento está sendo feito no GitHub (incluindo varias contribuições e feedbacks da comunidade de desenvolvimento). Considerando esta nova mentalidade e abordagem de trabalho, o time do ASP.NET escolheu uma plataforma para escrever e manter a documentação deste framework.
A documentação do ASP.NET 5 está disponível em https://docs.asp.net/ o qual é desenvolvido utilizando uma plataforma chamada Read the Docs. Esta plataforma utiliza Python, Sphinks e reStructuredText uma linguagem de marcação (parecido com o Markdown) para gerar uma documentação dos projetos, incluindo features como versionamento, disponibilização em pdf, html e epub.
Assim como o projeto do ASP.NET 5, sua documentação também é open source e mantida no GitHub https://github.com/aspnet/Docs. Neste post vou mostrar como é possível contribuir com a documentação do ASP.NET 5 e ajudar muitos outros desenvolvedores.
Para preparar o ambiente, primeiramente vamos instalar o Python e adicionar os diretórios dele no Path.
Após termos o Python executando, vamos instalar o Sphinks utilizando o gerenciador de pacotes do Python, o pip. Só abrir um cmd e executar:
Com o sphinx instalado, vamos atualizar o tema padrão que vem com ele:
pip install -U sphinx_rtd_theme
Trabalhando com a Documentação
Segundo o contributors guide da documentação, o primeiro passo é criar um fork do repositório:
Com isso vou clonar o repositório no meu computador, no meu caso eu estou utilizando o https://git-for-windows.github.io/, mas você pode utilizar a ferramenta da sua preferencia para trabalhar com o git:
git clone https://github.com/rodolfofadino/Docs.git
Feito isso, podemos executar o make.bat html e gerar os htmls da documentação:
Com isto temos a documentação acessível, dentro da pasta _build.
Ao olhar a estrutura do projeto ele é composto por arquivos .rst e alguns arquivos estáticos como imagens e exemplos de projetos.
Existem algumas maneiras de contribuir para o projeto, uma delas é encontrar e corrigir bugs e erros de códigos, formatações ou de linguagem. Outra maneira é ir em partes da documentação que ainda não foram escritas (aquelas que possuem uma chave inglesa)
Nestas partes interagir com a issue que exite no GitHub para aquela parte da documentação e ajudar a desenvolver. (exemplo da issue https://github.com/aspnet/Docs/issues/72).
Após criar um fork do projeto, precisaremos criar uma branch a partir da master e desenvolver o que vamos contribuir (seja uma correção ou uma nova parte da documentação).
Feito isso, é necessário abrir um Pull Request no GitHub para o projeto original.
https://github.com/aspnet/Docs/pull/610
Uma vez que o time avaliou e aceitou o Pull Request, o código que foi desenvolvido é integrado com a versão da master do projeto, e fica disponível no https://docs.asp.net/.