Suggerimenti per la documentazione di classe

Question

Siamo un negozio Microsoft, concentrato sull'utilizzo di C#. Abbiamo diversi progetti, inclusi siti Web, servizi Windows e librerie di classi, che incorporano commenti XML.

Sto cercando di generare una documentazione HTML in stile MSDN per ogni progetto e distribuirla in una posizione centralizzata a cui tutti gli sviluppatori possono facilmente accedere. Voglio anche automatizzare questi passaggi in modo che possano essere eseguiti a intervalli regolari, quindi io e gli altri sviluppatori non dobbiamo preoccuparci di ricordare di generare e distribuire nuova documentazione ogni volta che viene apportata una modifica. Ho guardato Sandcastle e Doxygen ed entrambi sembrano essere delle buone opzioni per generare la documentazione che voglio, ma ho bisogno di consigli su un buon modo per automatizzarne la generazione, come in un lavoro notturno o qualcosa del genere.

C'è qualcuno che sta facendo qualcosa del genere? Non sono venduto sul risultato finale essendo HTML; soprattutto se c'è un'idea migliore.

EDIT:

Apprezzo tutte le buone idee. Ci sono un paio di percorsi ora che posso indagare, ma non saprò quale funzionerà meglio fino a sporcarmi le mani. Il File Builder della Guida di Sandcastle sembra offrirmi le migliori opzioni per quello che sto cercando di fare, quindi darò un cenno del capo a tale suggerimento. Tuttavia, se avessi avuto più tempo per lavorare sulla soluzione XSLT e CSS per ottenere i dati XML in modo corretto, avrei seguito questo suggerimento.

Grazie ancora a tutti!

Answer 1

Dai uno sguardo allo Sandcastle Help File Builder. Questo utilizza progetti standalone, quindi puoi costruirli tutte le volte che vuoi (ad esempio ogni notte o come parte del tuo sistema continuous integration ogni volta che viene effettuato il check in di un cambio).

Answer 2

Lo faccio con i nostri progetti. Fondamentalmente usiamo doxywizard per configurare la configurazione Doxyfile, che imposterà le specifiche per l'html generato. Quindi, in una fase del build server invoco "doxygen doxyfile".

Il nostro Doxyfile è configurato per generare i file doxygen in un'area visibile dal nostro server web. Quindi, ogni commit to trunk provoca la ricostruzione automatica della documentazione.

Answer 3

Non è necessario alcun strumento di terze parti per generare una buona documentazione: il compilatore C# può inviare la documentazione dai commenti XML in XML e tutto ciò che serve è progettare un bel CSS per mostrarlo nel browser. Se non sei soddisfatto, puoi anche generare la tua transformazione XSLT prima dell'applicazione del CSS, as described here (cerca un esempio di CSS nei commenti!).

In alternativa è possibile utilizzare questa documentazione XML e migliorarla utilizzando qualcosa come NDoc. Ecco un nice article su come farlo, purtroppo un po 'obsoleto.

È possibile creare manualmente solo la documentazione del progetto in un singolo file XML eseguendo il compilatore con il parametro /doc:documentationfilename.xml.

È inoltre possibile indicare in Visual Studio (Proprietà progetto -> Documentazione) per aggiungere questa opzione a ogni build del progetto, in modo che il file XML venga generato ogni volta che si crea il progetto. È quindi possibile collegare gli eventi post-build per copiare il file XML nel repository.

È anche possibile configurare MS Build sul server Team Foundation per creare la documentazione e copiarla nel repository in modo simile (/p:DocumentationFile=fileName.xml);