in ASP.NET

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.

image

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.

image

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.

Preparando o Ambiente

Para preparar o ambiente, primeiramente vamos instalar o Python e adicionar os diretórios dele no Path.

https://www.python.org/downloads/

image

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:

pip install sphinx

image

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:

image

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

image

Feito isso, podemos executar o make.bat html e gerar os htmls da documentação:

make.bat html

image

Com isto temos a documentação acessível, dentro da pasta _build.

image

Ao olhar a estrutura do projeto ele é composto por arquivos .rst e alguns arquivos estáticos como imagens e exemplos de projetos.

PullRequest

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)

image

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

image

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/.

Bom espero que este post seja útil, estou a disposição para dúvidas, criticas e sugestões.

abs

Rodolfo