Domanda Genera automaticamente la documentazione html durante una compilazione con Sandcastle


Quali passi devo fare per ottenere automaticamente la documentazione HTML attraverso la fase di creazione in Visual Studio? Ho tutti i commenti sul posto e il file comments.xml che viene generato, e Sandcastle installato. Devo solo sapere cosa aggiungere alla fase post-generazione per generare i documenti.


20
2017-10-17 10:47


origine


risposte:


Alcune modifiche sono state fatte da quando è stata posta questa domanda. Sandcastle non include più SandcastleBuilderConsole.exe. Invece usa semplicemente vecchio MSBuild.exe.

Integrare questo con lo studio visivo qui è quello che ho fatto:

Inseriscilo nell'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

Questo farà sì che visual studio costruisca la tua documentazione, solo quando costruisci in modalità "Release". In questo modo non stai aspettando per sempre quando crei in modalità "Debug" durante lo sviluppo.

Un paio di note:

  • Il mio sistema è a 64 bit, se il tuo non è poi sostituito framework64 con framework nel percorso verso msbuild.exe.

  • Il modo in cui l'ho impostato è di documentare individualmente ogni progetto nella mia soluzione. Se si dispone di un file di progetto "Sandcastle Help File Builder" che include diversi progetti insieme, probabilmente si vuole sbarazzarsi di ProjectName\ e muoviti doc nella directory della soluzione. In questo caso, si desidera solo inserire i comandi evento Post-build nel progetto che è stato creato LAST nella propria soluzione. Se lo inserisci nell'evento Post-build per ogni progetto, ricostruirai la documentazione per ogni progetto che è stato creato. Inutile dire che resterai seduto un momento. Personalmente preferisco documentare ogni progetto individualmente, ma sono solo io.

Installazione di Sandcastle e "Sandcastle Help File Builder".

Se non sai come installare correttamente Sandcastle e "Builder di File Builder Sandcastle", procedi nel seguente modo:

  1. Scarica e installa Sandcastle da http://sandcastle.codeplex.com/ (Se si dispone di un sistema a 64 bit, sarà necessario aggiungere una variabile di ambiente Qui.

  2. Scarica e installa "Sandcastle Help File Builder" da http://shfb.codeplex.com/ (Ignora gli avvisi su MSHelp2 se ne ottieni. Non ne avrai bisogno.)

  3. Una volta installati, utilizzare "Sandcastle Help File Builder" per creare un nuovo progetto di documentazione. Quando ti chiede dove salvare il file, salvalo nella cartella della documentazione che hai nella tua soluzione / progetto. http://www.chevtek.com/Temp/NewProject.jpg

  4. Dopo aver creato un nuovo progetto dovrai scegliere il tipo di documentazione che desideri creare. Un file della guida di Windows compilato, un sito Web o entrambi. http://www.chevtek.com/Temp/DocumentationType.jpg

  5. Se il file di progetto SHFB è stato salvato nella directory in cui si desidera generare la documentazione, è possibile saltare questo passaggio. Ma se si desidera che la documentazione generata venga collocata altrove, è necessario regolare il percorso di output. http://www.chevtek.com/Temp/OutputPath.jpgNOTA: Una cosa da tenere a mente sul percorso di output (che mi ha frustrato per un'ora) è che quando si controlla il sito Web come tipo di documentazione, sovrascrive il contenuto nel suo percorso di output. Quello che trascurano di dirti è che SHFB ha ristretto intenzionalmente alcune cartelle dall'essere incluse come parte del percorso di output. Il desktop è una di queste cartelle. Il tuo percorso di output non può essere sul desktop, nemmeno una sottocartella di desktop. Non può nemmeno da Documenti, ma può essere una sottocartella dei miei documenti. Se si verificano errori durante la creazione della documentazione, provare a modificare il percorso di output e vedere se lo risolve. Vedere http://shfb.codeplex.com/discussions/226668?ProjectName=shfb per i dettagli su questo.

  6. Infine, dovrai aggiungere un riferimento al progetto che desideri documentare. Se stai facendo progetti individuali come faccio io, allora per ogni file di progetto SHFB che crei, farai riferimento al file .CSPROJ corrispondente. Se hai un progetto SHFB per l'intera soluzione, troverai il file .SLN per la tua soluzione. (sandcastle funziona anche se si fa riferimento alle DLL compilate, ma dal momento che lo si sta integrando con Visual Studio, trovo che abbia più senso fare riferimento ai file di progetto / soluzione. Ciò potrebbe anche significare che non importa quale progetto si fai l'evento post-build da quando fa riferimento al codice anziché alle DLL, ma è meglio essere sicuro e inserirlo nell'ultimo progetto che è stato creato) http://www.chevtek.com/Temp/AddSource.jpg

  7. Salvare il progetto e chiudere "Sandcastle Help File Builder". Ora tutto è configurato. Assicurati di inserire il file di progetto della documentazione nella cartella appropriata a cui puntano i comandi batch nell'evento Post-build.

Spero che il mio breve tutorial ti aiuti! È stato molto difficile per me trovare tutorial decenti che mi mostrassero come usare sandcastle, per non parlare di come integrarlo con Visual Studio. Speriamo che future ricerche su google mostrino questa domanda.


32
2017-10-17 10:51



Vi consiglio di installare Sandcastle Help File Builder da CodePlex.

Puoi eseguirlo dalla riga di comando, ad es. da un evento Post-Build. La più semplice riga di comando è:

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

Sandcastle è molto lento, quindi lo eseguo solo per Release Builds. Per fare ciò, crea un evento Post-Build con un comando simile al seguente, che passa il nome di configurazione a un file batch:

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

Quindi, all'interno del file batch, è possibile verificare se il primo argomento è "Rilascio" e in tal caso eseguire SandcastleBuilderConsole.exe.


6
2018-01-20 16:59



Un modo semplice per farlo come suggerito sopra è l'utilizzo del Generatore di file di aiuto di Sandcastle. Sono state apportate alcune modifiche al processo di compilazione dalla riga di comando e ora questi progetti possono essere creati con MSbuild invece di SandcastleBuilderConsole.exe. Quindi tutto ciò che devi fare è:

MSbuild.exe ProjectName.shfb


1
2017-10-17 10:54



Devo ammettere che trovo l'attuale versione di Sandcastle un po 'carente; per i progetti di grandi dimensioni è piuttosto lento e non è facile da integrare (poiché è ancora presto).

Per un uso regolare, trovo davvero più semplice puntare il riflettore in una cartella con i file dll e xml - IIRC, caricherà i file xml mentre navighi.

In più ho quasi sempre il catarifrangente aperto comunque ...

[modifica] selezionato e sì - i commenti xml vengono visualizzati nel pannello del disassemblatore


0
2017-10-17 11:09



Installa questi:

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

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

Quindi utilizzare la riga di comando NDocConsole.exe per generare documentazione in formato MSDN o CHM:

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

Io stesso ho creato uno strumento esterno per questo e gli ho dato una scorciatoia, ma come diceva il poster precedente puoi collegarlo a un evento postbuild e così via.

(PS Ho usato la configurazione di cui sopra per alcuni anni e sono molto felice con esso)


0