Gerar documentação html automaticamente durante uma compilação com Sandcastle

https://stackoverflow.com/questions/211693

03-07-2019
|

Pergunta

Que passos que eu preciso fazer para chegar HTML documentação automaticamente a construção através da etapa de compilação no Visual Studio? Eu tenho todos os comentários no local e o arquivo comments.xml sendo gerado, e Sandcastle instalado. Eu só preciso saber o que acrescentar à etapa de pós-construção, a fim de gerar os documentos.

Solução

Algumas mudanças foram feitas a partir desta pergunta foi feita. Sandcastle não inclui mais SandcastleBuilderConsole.exe. Em vez disso, usa simples MSBuild.exe de idade.

Para integrar esta com visual studio aqui é o que eu fiz:

Coloque isso em seu evento Post-Build:

IF "$(ConfigurationName)"=="Release" Goto Exit

"$(SystemRoot)\microsoft.net\framework64\v4.0.30319\msbuild.exe" /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)ProjectName\doc\DocumentationProjectName.shfbproj"

:Exit

Isto fará com que Visual Studio para construir a sua documentação, somente quando você criar no modo "Release". Dessa forma, você não está esperando para sempre quando você criar no modo de "depuração" durante o desenvolvimento.

casal notes A:

Meu sistema é de 64 bits, se o seu não é, então, substituir framework64 com framework no caminho para msbuild.exe.
A maneira que eu tê-lo configuração é documentar cada projeto na minha solução individualmente. Se você tem um "Sandcastle Help File Builder" arquivo de projeto que inclui vários projetos juntos, então você provavelmente vai querer se livrar de ProjectName\ e movimento doc no diretório solução. Neste caso, você vai querer colocar apenas os comandos evento Post-Build no projeto que é construído passado em sua solução. Se você colocá-lo no evento Post-Build para cada projeto, em seguida, você será reconstruir a sua documentação para cada projeto que é construído. Escusado será dizer, você vai estar sentado lá um tempo. Pessoalmente eu prefiro para documentar cada projeto individualmente, mas isso é só comigo.

Instalação Sandcastle e "Sandcastle Help File Builder".

Se você não sabe como chegar Sandcastle e setup "Sandcastle Help File Builder" corretamente, em seguida, siga estes passos:

Baixe e instale Sandcastle de http://sandcastle.codeplex.com/ (se você ter um sistema de 64 bits, você precisará adicionar uma variável de ambiente. As instruções são aqui .
Faça o download e instalar o "Sandcastle Help File Builder" do http://shfb.codeplex.com/ (ignorar avisos sobre MSHelp2 se você obter qualquer. você não vai precisar dele.)
Depois de ter os instalados, em seguida, usar o "Sandcastle Help File Builder" para criar um novo projeto de documentação. Quando se lhe pergunta onde deseja salvar o arquivo, salvá-lo na documentação pasta que você tem em sua solução / projeto. http://www.chevtek.com/Temp/NewProject.jpg
Depois de criar um novo projeto você precisa escolher que tipo de documentação que você deseja criar. Um arquivo compilado janelas de ajuda, um site, ou ambos. http://www.chevtek.com/Temp/DocumentationType.jpg
Se você salvou o arquivo de projeto SHFB no diretório onde você deseja que a documentação a ser gerado, então você pode pular esta etapa. Mas se você quiser a documentação gerada para ser colocado em outro lugar, então você precisa ajustar o caminho de saída. http://www.chevtek.com/Temp/OutputPath.jpg NOTA: Uma coisa a ter em mente sobre o caminho de saída (que me frustrado por uma hora) é que quando você tem website verificado como o tipo de documentação que você quer, ele vai substituir o conteúdo em seu caminho de saída. O que eles esquecem de dizer é que SHFB propositadamente restrita determinadas pastas de ser incluído como parte do caminho de saída. Desktop é um tal pasta. Seu caminho de saída não pode estar no ambiente de trabalho, nem mesmo uma sub-pasta da área de trabalho. Não pode por meus documentos, quer, mas pode ser uma subpasta dos meus documentos. Se você receber erros ao construir a documentação, tente alterar o caminho de saída e ver se isso resolve o problema. Veja http://shfb.codeplex.com/discussions/226668?ProjectName=shfb para obter detalhes sobre isso.
Finalmente, você precisará adicionar uma referência para o projeto que você deseja documento. Se você estiver fazendo projetos individuais como eu, em seguida, para cada arquivo de projeto SHFB você cria, você vai referenciar o arquivo .csproj correspondente. Se você tem um projeto SHFB para toda a sua solução, então você teria que encontrar o arquivo .sln para a sua solução. (Castelo de areia também funciona se você faz referência as DLLs compilados, mas desde que você está integrando-o com o Visual Studio eu acho que faz mais sentido para fazer referência os arquivos de projeto / solução em vez disso. Isso também pode significar que ele realmente não importa o que você projeta fazer o evento pós-compilação em uma vez que é referenciando o código em vez das DLLs, mas é melhor estar seguro e colocá-lo no último projecto que é construído) http://www.chevtek.com/Temp/AddSource.jpg
Salvar o projeto e você pode fechar "Sandcastle Help File Builder". Agora tudo está configurado. Só não se esqueça de colocar o arquivo de projeto de documentação na pasta apropriada que o lote comandos ponto no evento pós-compilação.

Espero que o meu pequeno tutorial ajuda-lo! Foi muito difícil para mim encontrar qualquer tutoriais decentes mostrando-me como usar castelo de areia, e muito menos como integrá-lo com o estúdio visual. Esperemos futuro pesquisas do Google irá transformar-se esta questão.

Outras dicas

Eu recomendo que você instale Sandcastle Help File Construtor de Codeplex .

Você pode executar este a partir da linha de comando, por exemplo, de um evento Post-Build. A linha de comando mais simples é:

<install-path>\SandcastleBuilderConsole.exe ProjectName.shfb

Sandcastle é muito lenta, então eu só executá-lo para compilações Release. Para fazer isso, criar um evento pós-compilação com um comando algo como o seguinte, que passa o nome da configuração de um arquivo de lote:

CALL "$(ProjectDir)PostBuild.cmd" $(ConfigurationName)

Então, dentro do arquivo de lote, você pode testar se o primeiro argumento é "Release" e se assim for executado SandcastleBuilderConsole.exe.

Uma maneira fácil de fazer isso como sugerido acima está usando Sandcastle Help File Builder. Houve algumas alterações feitas no processo de construção da linha de comando e, agora, esses projetos podem ser construídos com MSbuild vez de SandcastleBuilderConsole.exe. Então tudo que você tem a fazer é:

MSBuild.exe ProjectName.shfb

Eu devo admitir que eu encontrar a versão atual do Sandcastle um pouco falta; para grandes projectos é bastante lento, e não é fácil de integrar (uma vez que ainda é cedo).

Para uso regular, eu realmente achar que é mais fácil apenas para ponto refletor em uma pasta com os arquivos DLL e XML -. IIRC, ele irá carregar o arquivo xml (s) antes de navegar

Além disso, eu quase sempre têm refletor de qualquer maneira aberta ...

[editar] marcada, e sim - comentários xml mostrar no painel desmontador

Instale estes:

NDoc: http://prdownloads.sourceforge.net/ndoc /NDoc-v1.3.1.msi?download

HTML Help Workshop: http :? //www.microsoft.com/downloads/details.aspx FamilyID = 00535334-c8a6-452f-9aa0-d597d16580cc & displaylang = en

Em seguida, use a linha de comando NDocConsole.exe para gerar a documentação em qualquer forma MSDN ou CHM:

@c: \ progra ~ 1 \ NDoc \ NDocConsole.exe MyCode.dll, MyCode.xml -Documenter = MSDN-CHM

Eu me fizeram uma ferramenta externa para isso e deu-lhe um atalho, mas como o cartaz anterior disse que você pode ligá-lo a um evento postbuild e lá vai você.

(PS Tenho vindo a utilizar a configuração acima por alguns anos agora e estou muito feliz com isso)

Licenciado em: CC-BY-SA com atribuição

Não afiliado a StackOverflow