Dove dovrebbe essere conservata la documentazione di progetto (requisiti, ecc.) In un tipico progetto maven.Dove dovrebbe essere conservata la documentazione di progetto in un tipico progetto maven
Nessuna delle directory elencate nella pagina Introduction to the Standard Directory Layout è un candidato evidente.
Purtroppo non c'è convenzione. Se vuoi che la documentazione faccia parte del sito generato, ovviamente /src/site è un buon posto. Forse puoi persino scrivere la documentazione nel formato APT?
Ma più probabilmente si dispone di un set di doc, pdf e xls file, grafica, e-mail, ecc è possibile metterli sotto /src/site come bene e mettere collegamenti ipertestuali nel sito o ... definire la propria convention , purtroppo. In genere ho visto /src/main/doc(s), /src/doc(s) o anche /doc(s).
Non si desidera posizionare la documentazione in /src/main/resources o src/main/webapp, in quanto i file faranno parte degli artefatti costruiti (JAR/WAR) che sono raramente desiderati.
Non è SRC piuttosto per la fonte? – Line
http://www.sonatype.com/books/mvnref-book/reference/site-generation-sect-dir-struct.html raccomanda la seguente struttura
sample-project
+- src/
[..]
+- resources/
| +- images/
| | +- banner-left.png
| | +- banner-right.png
| |
| +- architecture.html
| +- jira-roadmap-export-2007-03-26.html
[..]
Non so perché Joao ha modificato questo post invece di postare un suggerimento alternativo. Mette la cartella delle risorse sotto la cartella del sito che certamente è anche un'opzione valida. Il suggerimento che ho postato/citato utilizza una cartella delle risorse al livello superiore accanto alle cartelle src e del sito (vedi link nel post). Uno non vuole necessariamente includere tutta la documentazione nel sito. – RobE
Mi dispiace @RobE, mio errore. –
Secondo il maven-javadoc-plugin:
Il parametro
<javadocDirectory/>può essere utilizzato per includere risorse aggiuntive, come HTML o le immagini, nel javadoc generato. È quindi possibile collegarsi a queste risorse nei commenti javadoc. Per impostazione predefinita, tutte le risorse javadoc si trovano nella directory${basedir}/src/main/javadoc. Si noti che è necessario impostare il parametrodocfilessubdirsper copiarli.
Vedi la differenza tra la documentazione in generale e JavaDoc? :) – Line
Un po '. Se si visualizza JavaDoc come un generatore di formato/documentazione, il problema non è mai la documentazione delle sole API, ma la scrittura dei documenti intorno a loro che spiegano il loro uso. Avere quel * in * JavaDocs/Code e il collegamento alle API sembra sempre una buona idea. Se stai documentando qualcosa * diverso * dalle API, penserei che potrebbe essere usato qualcos'altro (ad es. Markdown). – Alun
Vorrei votare per "/ docs". Tutto sotto '/ src' è un mondo di maven, meglio non scherzare con quello. Penso anche che il progetto stesso non sia utile per il salvataggio della documentazione. Potresti installare wiki. –
In tutti i file di origine vai sotto/src. I documenti che si modificano sono file sorgente, dovrebbero andare in/src da qualche parte. Se si inizia ad aggiungere nuove directory di primo livello con poca probabilità, il progetto non segue le convenzioni di esperti e sarà difficile da comprendere per gli altri. –