Dónde se debe almacenar la documentación del proyecto (requisitos, etc.) en un proyecto típico de maven.Dónde debe almacenarse la documentación del proyecto en un proyecto típico de maven
Ninguno de los directorios enumerados en la página Introduction to the Standard Directory Layout es un candidato obvio.
Desafortunadamente no hay convención. Si desea que la documentación sea parte del sitio generado, obviamente /src/site es un buen lugar. ¿Tal vez incluso puede escribir la documentación en el formato APT?
Pero lo más probable es que haya un conjunto de doc, pdf y xls archivos, gráficos, correos electrónicos, etc. Usted puede colocarlas bajo /src/site así y poner hipervínculos en el sitio o ... definir su propia convención , tristemente. Por lo general, he visto /src/main/doc(s), /src/doc(s) o incluso /doc(s).
No desea colocar su documentación en /src/main/resources o src/main/webapp, ya que los archivos formarán parte del artefacto construido (JAR/WAR) que rara vez se desea.
¿No es mejor para la fuente? – Line
http://www.sonatype.com/books/mvnref-book/reference/site-generation-sect-dir-struct.html recomienda la siguiente estructura
sample-project
+- src/
[..]
+- resources/
| +- images/
| | +- banner-left.png
| | +- banner-right.png
| |
| +- architecture.html
| +- jira-roadmap-export-2007-03-26.html
[..]
No sé por qué Joao editó esta publicación en lugar de publicar una sugerencia alternativa. Coloca la carpeta de recursos debajo de la carpeta del sitio, que ciertamente también es una opción válida. La sugerencia que publiqué/citó utiliza una carpeta de recursos en el nivel superior junto a las carpetas de src y del sitio (ver el enlace en la publicación). Uno no necesariamente quiere incluir toda la documentación en el sitio. – RobE
Lo siento @RobE, mi error. –
Según la maven-javadoc-plugin:
El parámetro
<javadocDirectory/>se puede utilizar para incluir los recursos adicionales, como HTML o imágenes, en el Javadoc generado. A continuación, puede vincular a estos recursos en sus comentarios de javadoc. Por defecto, todos los recursos de javadoc están en el directorio${basedir}/src/main/javadoc. Tenga en cuenta que debe establecer el parámetrodocfilessubdirspara copiarlos.
¿Ves la diferencia entre la documentación en general y JavaDoc? :) – Line
Algo. Si ve JavaDoc como un generador de formato/documentación, el problema nunca es documentar solo las API, sino escribir los documentos a su alrededor que expliquen su uso. Tener esa * en * JavaDocs/Code, y enlazar a las API, siempre parece ser una buena idea. Si está documentando algo * * distinto de las API, creo que se podría usar algo más (por ejemplo, el descuento). – Alun
Yo votaría por '/ docs'. Todo bajo '/ src' es maven world, mejor no meterse con eso. También creo que el proyecto en sí no es bueno para guardar la documentación. Considera instalar wiki. –
En maven, todos los archivos fuente van por/src. Los documentos que edita son archivos fuente, deben ir por/src a alguna parte. Si comienza a agregar nuevos directorios de alto nivel de cualquier forma, su proyecto no seguirá las convenciones de expertos y será difícil de comprender para otros. –