Maintenance en double - code et documentation [fermé]

Question

Ce n'est peut-être pas le meilleur titre. J'apprécierais que quelqu'un en propose un meilleur après avoir lu mon problème. De plus, je tiens à dire dès le départ que je suis en grande partie autodidacte sur Internet. Il peut donc y avoir de nombreux outils que je ne connais pas.

Je maintiens un logiciel implémentant le concept de programmation à base de flux (FBP) en Java et en C #. Pour chacun d'entre eux, j'ai du code sur:

• mon site web
• Système de diffusion de fichiers SourceForge (fichiers zip ou jar)
• SVN SourceForge

De plus, j'ai des références de version et des descriptions (parfois partielles) sur:

• mon site web (HTML)
• mon wiki
• Javadoc

Il existe également un outil de dessin, également sur mon site Web et sur SourceForge, qui doit connaître la dernière version de la version Java du code FBP.

Tout est bien réticulé, mais parfois une référence me manque! Il y a quelques jours, je me suis rendu compte que je n'avais pas mis à jour SourceForge News pour mon projet depuis longtemps, j'ai donc dû me débrouiller pour le faire :-)

Je me rends compte que certains de ces véhicules sont probablement redondants, mais en général, je ne sais pas qui regarde quoi.

Ma question est donc de savoir s’il existe un moyen de réduire tous ces frais généraux, par exemple. un HTML " imbed " Cette fonction serait utile, afin que je puisse au moins stocker le dernier numéro de version à un endroit. Je peux probablement simplifier les références croisées Java, mais l’inter-langage serait encore plus agréable, mais peu probable, je suppose.

Toutes les idées seraient les bienvenues.

Answer 1

Il me semble que vous souhaitez mettre à jour et conserver votre documentation dans le cadre de votre processus de création / déploiement, par exemple.

1. construire
2. test unitaire, etc.
3. compiler la documentation
4. déploie des versions
5. déployer la documentation compilée

sinon, vous êtes toujours toujours à la poursuite de votre queue. De toute évidence, le déploiement de la documentation nécessitera différentes solutions quant à sa destination (copie sur votre site Web, mise en FTP ailleurs, etc.).

Je ne suis pas sûr qu'il existe une panacée pour tout cela. Je conserve les numéros de version dans les fichiers de propriétés / fichiers de configuration et effectue les recherches / remplacements appropriés. La documentation du code, dans la mesure du possible, va dans le code lui-même, puis est prétraitée dans ma construction (étape 3 ci-dessus).

Avez-vous vu / utilisé doxygen ? Cela répond à vos besoins multilingues et est bien établi pour la création / maintenance de la documentation.

Answer 2

Il semble que vous deviez automatiser votre processus de construction / publication. Je lis cet article sur O'Reilly il y a longtemps - il semble que vous avez tous les deux des situations assez similaires? Sa solution fait un usage intensif de Python, mais à tout le moins, elle pourrait vous donner quelques idées.