Suggerimenti documentazione relativa alla classe

Question

Siamo un negozio di Microsoft, concentrata sull'uso C #. Abbiamo diversi progetti, tra cui siti web, servizi di Windows, e librerie di classi, che i commenti incorporare XML.

Sto cercando di generare documentazione HTML in stile MSDN per ogni progetto e distribuirlo ad una posizione centralizzata che tutti gli sviluppatori possono facilmente accedere. Voglio anche di automatizzare questi passaggi in modo che possano essere eseguiti a intervalli regolari in modo da, e gli altri sviluppatori, non ho bisogno di preoccuparsi di ricordarsi di generare e distribuire nuova documentazione ogni volta che viene apportata una modifica. Ho guardato Sandcastle e Doxygen ed entrambi sembrano essere buone opzioni per la generazione della documentazione che voglio, ma ho bisogno di un consiglio su un buon modo per automatizzare la generazione di esso, come in un lavoro notturno o qualcosa del genere.

Chiunque là fuori a fare qualcosa di simile? Io non sono venduti sul risultato finale essendo HTML; soprattutto se v'è una migliore idea.

EDIT:

Apprezzo tutte le idee buone. Ci sono un paio di percorsi ora che posso indagare, ma non voglio sapere quale funziona meglio fino a quando ho il mio sporca le mani. Il file Sandcastle Aiuto Builder sembra offrire me le migliori opzioni per quello che sto cercando di fare, quindi darò il cenno a tale suggerimento. Tuttavia, se avessi avuto più tempo per lavorare sulla soluzione XSLT e CSS per ottenere i dati XML in cerca solo di destra, mi piacerebbe portare avanti prima che il suggerimento.

Grazie ancora a tutti!

Answer 1

Date un'occhiata al File Sandcastle Aiuto Builder . Questo utilizza standalone progetti, in modo da poterli costruire tutte le volte che ti piace (per esempio di notte, o come parte della vostra continuo sistema di integrazione ogni volta che un cambiamento è registrato).

Answer 2

Non è necessario alcun strumenti di terze parti per generare buona documentazione: C # compilatore può emettere la documentazione da XML-commenti in XML e tutto ciò che serve è quello di progettare un CSS bella di mostrarlo in del browser. Se non siete soddisfatti, si può anche generare il proprio XSLT-transoformation prima di applicare CSS, come descritto qui (aspetto per un esempio di CSS nei commenti!).

In alternativa si può prendere questa documentazione XML e migliorarlo utilizzando qualcosa di simile NDoc . Ecco una bell'articolo su come farlo, purtroppo un po 'datato.

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

Si può anche indicare a Visual Studio (Proprietà progetto -> Documentazione) per aggiungere questa opzione per ogni build del vostro progetto, in modo che il file XML verrà generato ogni volta che si genera il progetto. È quindi possibile collegare gli eventi post-generazione per copiare il file XML al repository.

È possibile anche impostare il MS costruire da Team Foundation Server per costruire la documentazione e copiarlo al repository in modo simile (/p:DocumentationFile=fileName.xml);

Answer 3

I do that with our projects. Basically we use doxywizard to set up the configuration Doxyfile, which will set the specifications for the generated html. Then, in a build server step I invoke "doxygen doxyfile".

Our Doxyfile is configured to generate the doxygen files in an area visible from our webserver. So, each commit to trunk causes documentation to be rebuilt automatically.