Mantenimiento duplicado: código y documentación [cerrado]

Question

Puede que este no sea el mejor título: agradecería que alguien encontrara uno mejor después de leer mi problema. Además, quiero decir por adelantado que en gran medida soy autodidacta en Internet, por lo que puede haber muchas herramientas que no conozco.

Mantengo un software que implementa el concepto de programación basada en flujo (FBP) en Java y C #. Para cada uno de estos, tengo código en:

• mi sitio web
• Sistema de lanzamiento de archivos SourceForge (archivos zip o archivos jar)
• SourceForge SVN

Además, tengo referencias de versión y descripciones (a veces parciales) en:

• mi sitio web (HTML)
• mi wiki
• Javadoc

También hay una herramienta de dibujo, también en mi sitio web y en SourceForge, que debe conocer la última versión de la versión Java del código FBP.

¡Todo está muy bien entrecruzado, pero a veces echo de menos una referencia! Hace unos días, me di cuenta de que no había actualizado SourceForge News para mi proyecto en mucho tiempo, así que tuve que apresurarme y hacer eso :-)

Me doy cuenta de que algunos de estos vehículos son probablemente redundantes, pero en general, no sé quién está mirando qué.

Entonces mi pregunta es si hay una manera de reducir toda esta sobrecarga, por ejemplo. un HTML "incrustado" La función sería buena, por lo que al menos puedo almacenar el último número de versión en un solo lugar. Probablemente pueda simplificar las referencias cruzadas de Java, pero entre idiomas sería aún más agradable, pero improbable, supongo.

Cualquier idea sería bienvenida.

Answer 1

Me parece que desea actualizar y mantener su documentación como parte de su proceso de compilación / implementación, por ejemplo,

1. construir
2. prueba unitaria, etc.
3. compilar documentación
4. desplegar compilaciones
5. desplegar documentación compilada

de lo contrario, siempre estarás persiguiendo tu cola. Obviamente, la implementación de la documentación requerirá diferentes soluciones sobre hacia dónde va (por ejemplo, copiada a su sitio web, FTPed en otro lugar, etc.)

No estoy seguro de que haya una panacea para todo esto. Mantengo los números de versión en los archivos de propiedades / archivos de configuración, y hago búsquedas / reemplazos apropiados. La documentación del código siempre que sea posible va en el código mismo, y luego eso está preprocesado en mi compilación (paso 3 anterior).

¿Ha visto / usado doxygen ? Eso manejará sus requisitos multilingües y está bien establecido para crear / mantener documentación.

Answer 2

Parece que necesita automatizar su proceso de compilación / publicación. Leí este artículo en O'Reilly hace un tiempo. Parece que ambos tienen situaciones bastante similares? Su solución hace un uso intensivo de Python, pero al menos, podría darle algunas ideas.