Documenter ses projets

 // accueil created: 2004-05-14 

Rubriques
Lipforge dies and reborns CVS et Gforge CVS et binaires Projets : publics / privés Documenter ses projets
Questions ou commentaires ?
Suggestions ou conseils ?

GForge et la documentation des projets

GForge propose plusieurs options pour la documentation des projets. Nous avons, par ailleurs, ajouté quelques éléments pour en faciliter l'usage. C'est ce qui fait l'objet de ce document.

Que propose GForge ?

Deux approches sont possibles, notez d'ailleurs qu'elles ne sont pas contradictoires. La première est un site Web que vous composez vous-même. La seconde est un outil de GForge qui vous permet de gérer une série de fichiers qui vont constituer votre documentation.

Un site Web

Le lien « Project Home Page »

A tout projet on peut associer un site Web. C'est lui qui est invoqué à travers le lien « Project Home Page » de l'onglet « Summary » du projet. Par défaut, l'adresse correspondante est http://lipforge.ens-lyon.fr/www/nomProjet/. A priori il n'y a pas de document à cette adresse et cliquer sur le lien génère une erreur.

Vous pouvez, en tant qu'administrateur d'un projet, modifier cette information :

  • allez dans l'onglet « Admin » du projet ;
  • cliquez sur le lien « Edit Public Info » ;
  • modifiez la rubrique « Homepage Link ».

Vous pouvez faire ainsi pointer le lien « Project Home Page » vers la page Web de votre (y compris sur un autre serveur que Lipforge).

Intérêt de la solution

Sur un site Web indépendant, vous êtes totalement libre de la présentation et de la structure de vos informtaions. De nombreux projets sur SourceForge procèdent de cette façon. Ils proposent quelques liens vers SourceForge, uniquement pour les fonctionnalités qu'ils jugent les plus utiles (p. ex. le téléchargement).

Le dossier /local/chroot/groups/

Par défaut, le lien http://lipforge.ens-lyon.fr/www/nomProjet/ correspond au contenu fichier index.html (ou encore index.shtml ou enfin index.php) du répertoire /local/chroot/groups/nomProjet/htdocs du serveur. Un développeur du projet peut se connect par SSH sur Lipforge, créer et éditer ce fichier ainsi que tous ceux qui constituent le site Web.

Cela dit, cette manière de faire peut être laborieuse car on ne dispose pas nécessairement sur Lipforge des outils les plus adaptés pour éditer des pages HTML et/ou gérer un site. Il est possible de travailler localement, sur son poste de travail, et de transferer le site par la commande scp our rsync à travers SSH au "bon" endroit sur Lipforge.

Il existe encore une autre possibilité qui consiste à gérer son site avec le dépôt CVS du projet. La manière de procéder est, en tant que développeur du projet, la suivante :

  • on réalise une première mouture du site sur son poste local ;
  • on utilise la commande import pour créer un module nommé htdocs et y transferer tout le site dans le dépôt CVS du projet ;
  • on se connecte par SSH sur le serveur et on lance la commande updateWebSite nomProjet ;
  • cette commande met à jour le répertoire /local/chroot/groups/nomProjet/htdocs avec le contenu du module htdocs du dépôt du projet par la commande cvs export.

Pour les mises à jour à jour ultérieures, l'auteur manipule de module htdocs comme il le ferait pour du code (checkout, modification, commit). Une fois cela terminé, il se connecte par SSH sur Lipforge et lance la commande updateWebSite.

L'intérêt de cette façon de faire est que l'on dispose des fonctionnalités de CVS pour la gestion du site Web (gestion des versions), que le site Web est sauvegardé (comme l'ensemble des dépôts CVS) et que la mise à jour est particulièrement simple. Les inconvénients sont ceux de CVS. En particulier, le travail avec des fichiers binaires suppose des précautions particulières (voir ici).

Le système de gestion de la documentation de GForge

GForge vous permet de gérer un ensemble de documents qui seront présentés au public à travers l'onglet « Doc » ou le lien « DocsManager : Project Documentation » du projet.

Présentation des documents

Les documents sont proposés sous forme de liste dans une page Web. Cette liste peut être décomposée en plusieurs rubriques qui permettent une classification sommaire des documents. La classification n'a qu'un seul niveau mais on peut créer autant de titres que l'on veut (via l'interface du gestionnaire de documentation) voire modifier les titres déjà enregistrés (mais pas les supprimer).

Edition des documents

Une fois un document chargé, il peut être édité dans une « textarea » HTML, cela n'a de sens que pour des fichiers texte (texte « pur » ou, par exemple, HTML).

Gestion des documents

Un document déposé n'est pas automatiquement publié. Seuls les gestionnaires de la documentation ont le pouvoir de le mettre en ligne. L'interface de GForge propose tous les moyens pour, d'une part, désigner les gestionnaires et, d'autre part, réaliser les opérations telles qu'approbation ou rejet d'une proposition. Notez que le public peut proposer des documents. Les gestionnaires apprennent qu'ils ont des documents à réviser en consultant l'onglet "My Page". Dans GForge il est possible de déléguer très largement et de manière très souple les responsabilités de gestion. Être un gestionnaire de documentation ne suppose pas être aussi un développeur comme c'était le cas dans la solutions du site Web.

Conclusion

Chaque approche présente des avantages et des inconvénients. L'avantage essentiel du site Web autonome est la souplesse. Son principal inconvénient est qu'il faut tout réaliser manuellement (à moins d'utiliser un outil de gestion de site qui peut être bien plus riche que les outils offert par GForge). L'avantage des outils de GForge c'est qu'ils existent déjà et sont faciles à utiliser. Leur principal inconvénient est leur rigidité et leur faible capacité de catégorisation.


Nouvelles & Nouveautés
Lipforge closing is not the end of the story: join us on CBP-Forge powered by Redmine!
Sad but true, Lipforge is closing.
 2004-05-18
CVS et binaires
On peut aussi gérer des fichiers binaires avec CVS. Mais quelques précautions s'imposent pour éviter les déconvenues.
 2004-05-14
CVS
Quelques conseils pour utiliser CVS sur LipForge.
 2004-05-14
Documenter ses projets
Gforge vous offre plusieurs possibilités pour documenter vos projets. Quelques éclaircissements à ce propos.
 2004-05-14
Public / privé
Gforge est un outil plutôt destiné aux projets publics mais il permet aussi de travailler de manière plus discrète... quitte ensuite à sortir en pleine lumière !

shareright © 2002 Phlash