Les documents proposés sur ce site ont été testés et validés par différentes installations mais ne sauraient engager la responsabilité de la société en cas de problèmes ou de pertes de données si les modifications n'ont pas été réalisées par la société elle même.

Table des matières

11-Créer la documentation du paquet

Un outil fournit par debdevel-tools permet de générer des squelettes de documentation. Ces squelettes sont des bases de documentation dont les éléments ont été pris dans les fichiers et qu'il vous suffit d'éditer pour créer facilement et rapidement une documentation/fiche technique pour votre programme.

Les fiches de documentation des programmes (par exemple 6-fiche_du_programme_debdevel-tools) ont été crées grâce à cette fonction.

Vous constaterez que le maximum d'informations est récupéré depuis les fichiers et les réglages que vous aurez auparavant effectué. Si vous vous astreignez à suivre les indications suivantes lors de la création de vos programme, la rédaction de documentation (souvent négligée par les développeurs) ne vous prendra que très peu de temps avec une facilité déconcertante.

Non seulement la documentation sera facile à générer, mais vos programmes seront plus explicites.

Lancement de la création de la documentation

Effectuez un clic droit sur le paquet dont vous voulez créer un squelette de documentation, puis choisissez scripts/Développement/Documentation/Générer un squelette…/Format xxx.

Vous pouvez générer un squelette au format dokuwiki ou HTML avec les modules de base. D'autres formats pourront venir s'ajouter par la suite.1)

La documentation est générée dans le fichier PAQUET/usr/share/doc/PAQUET/PAQUET.txt 2)

Captures

Sections complétées automatiquement

  • Présentation : Le contenu de cette section correspond à la description courte du paquet, entrée par l'utilisateur à la création du paquet (informations contenue dans le fichier debian/control).
  • Dépendances : Le contenu de cette section correspond aux dépendances du paquet, entrées par l'utilisateur à la création du paquet (informations contenue dans le fichier debian/control).
  • Description : Le contenu de cette section correspond à la description longue du paquet, entrée par l'utilisateur à la création du paquet (informations contenue dans le fichier debian/control).
  • Captures d'écran : Si des images sont présentes dans le dossier PAQUET/usr/share/doc/PAQUET/screenshots, elles sont ajoutées au fichier dans le format adéquat.
  • Date de création: Cette valeur est relevée dans le fichier debian/changelog. La valeur dans ce fichier est générée lors de la création du paquet.
  • Auteur : Cette valeur est relevée dans le fichier debian/control. Cette valeur est générée à la création du paquet selon les réglages des préférences du programme debdevel.
  • Informations sur le paquet : Ces informations proviennent du fichier debian/control
  • Fichiers inclus : Arborescence du paquet au moment de la création de la documentation.
  • Fichiers liés au fonctionnement : Ce sont les fichiers présents dans le répertoire etc du paquet au moment de la création de la documentation.
  • Commandes et programmes : Ce sont les fichiers présents dans les répertoires habituels d'exécutables (/bin, /usr/bin, /usr/local/bin) du paquet.
  • Lancement : Si un ou plusieurs fichiers .desktop, qui sont les lanceurs de programmes), sont présents dans le répertoire PAQUET/usr/share/applications, le placement de chacun des ces lanceurs est relevé et listé.

Autres sections

Les autres sections sont affichées et non remplies automatiquement. Vous pouvez les remplir manuellement si elles concernent le programme, ou les supprimer si vous n'en avez pas l'utilité.

Génération d'un nouveau squelette de documentation

Si une documentation a déjà été générée dans le fichier PAQUET/usr/share/doc/PAQUET/PAQUET.txt, la nouvelle documentation est générée dans le fichier PAQUET/usr/share/doc/PAQUET/PAQUET_2.txt afin de ne pas perdre les modification manuelles éventuellement ajoutées au premier fichier.

Le fichier PAQUET/usr/share/doc/PAQUET/PAQUET_2.xxx est écrasé par une nouvelle génération de squelette de documentation ! N'apportez pas de modifications manuelles à ce document, elles seraient perdues en cas de nouvelle création de squelette de documentation.

Utilisez ce fichier pour mettre à jour le premier squelette par des copier/coller.

Informations relevées dans les fichiers programme

Le programme de documentation peut relever des informations supplémentaires dans chacun des fichiers rencontrés:

  • L'auteur: Il suffit de placer dans l'entête du fichier une ligne contenant le texte ”# Auteur :” avec les informations sur l'auteur sur la même ligne. Attention, les espaces sont importants. exemple:
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# Auteur : manuel BERROCAL <manu.berrocal@absolacom.com>
# Date: 20/08/2008
  • La description du fichier/programme : Il suffit de placer dans l'entête du fichier une ligne contenant le texte ”# Description :” avec les informations sur le programme sur la même ligne. Attention, les espaces sont importants. exemple:
#!/bin/bash
# script bash
# Description : script lançant la génération du miroir local pour être utilisable avec apt
# Auteur : manuel BERROCAL <manu.berrocal@absolacom.com>

Le résultat sera celui ci:

  • /usr/bin/compile_and_move :
    • script associant les opérations de compilation en deb et déplacement sur le miroir (manuel BERROCAL manu.berrocal@absolacom.com)
1) Vous pouvez aussi contribuer en rédigeant un programme générant une documentation dans un autre format en vous inspirant des programmes fournis
2) pour le format docuwiki. Pour les autres format, l'extention est celle du format choisi

Outils personnels