Objetivo

Durante o desenvolvimento do MSBuildCodeMetrics, uma das coisas que eu queria era exercitar um pouco de práticas de “produção” em relação ao software. Por isso, desde o começo mantive as práticas de build, testes unitários, etc.

Na hora de realizar o primeiro release, queria criar a documentação da API, da mesma forma que gosto de recebê-las. Acabei conseguindo chegar neste modelo: MSBuildCodeMetrics Release 0.1.0 – online documentation.

Não tinha a menor idéia de como fazer isso e iniciei algumas pesquisas. A idéia desse post é compartilhar um pouco do aprendizado neste processo.

Documentando os fontes

A primeira coisa para gerar este tipo de documentação, é começar a documentar os fontes. No topo de cada classe, adicionando 3 barras (///), o Visual Studio automaticamente cria o comentário no estilo:

	/// <summary>
	/// This class is responsible for running all metrics computations.
	/// </summary>
	public class CodeMetricsRunner
	{
	}

O mesmo tipo de comentário vale para métodos.

O próximo passo é fazer o Visual Studio gerar os XML’s para esse tipo de comentário. Isso também é simples. É só entrar nas propriedades do projeto, no item Build, quase no final das opções existe uma “XML documentation file”. Habilitando essa opção e recompilando o projeto, você perceberá que o Visual Studio gerou um xml junto com o binário compilado (no /bin/Debug ou /bin/Release).

SandCastle e SandCastle Help File Builder

Quando comecei a pesquisar as alternativas para gerar documentação, percebi que no mundo Microsoft o SandCastle era mais usado. Parece que a Microsoft meio que o está abandonando, mas até lá parecer ser a melhor opção. A outra opção seria o Doxygen, usado em diversos outros projetos também.

Pesquisei em diversos foruns e percebi que o SandCastle somente era um pouco complexo de trabalhar e que o Eric Woodruf já tinha criado um projeto chamado SandCastle Help File Builder. Este projeto já contém todo um “kit” de utilitários para trabalhar com SandCastle, uma mini IDE para editar os documentos e facilitar todo o processo. Resolvi ir por este caminho.

Instalando o SandCastle Help File Builder

Uma das coisas que eu gostei do SandCastle Help File Builder foi a Guided Installation que ele possui. Ele ajuda a encontrar e instalar todos os pré-requisitos.

Uma vez finalizado, o SHFB instala os pré-reqs do SandCastle e sua pequena IDE que apesar de simples, funciona.

Criando a documentação

Uma vez tendo tudo instalado, basta abrir a “SandCastle Help File Builder IDE”, File | New Project. Os arquivos de projeto (.shfbproj) são arquivos MSBuild, o que simplifica bastante executá-los de dentro do seu processo de build.

Após criar o projeto, basta ir no Project Explorer (da IDE do SHFB), em Documentation Sources e adicionar os seus .xml e .dll gerados pelo Visual Studio. A documentação para a API será totalmente gerada a partir do fonte.

A parte “conceitual” da documentação, basta adicionar um novo “Content Layout”. É nesse arquivo que você define a ordem e a estrutura dos tópicos.

Você pode criar tópicos personalizados à sua própria vontade. A notação é um xml (não encontrei facilmente um schema detalhando todo o padrão), mas é relativamente fácil entender a estrutura do documento.

Nas opções do projeto é possível escolher também se você quer gerar pdf, chm, html e outros. Eu preferi ficar no CHM e no HTML.

Era isso.