wiki:Doc/ProjStruct

Recommandations pour la structuration d'un projet

Cette note présente quelques éléments pour structurer un projet Trac, en particulier les page du WiKi. Ces recommandations sont issues de l'expérience de la gestion de quelques projets mais ne sont en rien obligatoires. Leur but est d'aider à conserver un site gérable quand le nombre de documents augmente et à maintenir une navigation facile dans les documents.

Organisation des pages du Wiki

Le WiKi de Trac permet une organisation hiérarchique des pages. Toute l'arborescence des pages du WiKi se trouve sous l'url 'wiki/' du projet.

La recommandation est de créer une hiérarchie de documents correspondant aux différentes catégories de pages. Par exemple :

        wiki/Doc
        wiki/Divers
        wiki/Action

Chacun de ces niveaux peut lui-même être subdivisé. Par exemple :

        wiki/Doc/Apache
        wiki/Doc/Trac

Il y a plusieurs avantages à une telle structuration :

  • Si on demande la liste de toutes les pages du WiKi, on visualise plus facilement les pages qui ont un lien entre elles. On peut obtenir un effet similaire en utilisant un préfixe commun aux pages traitant du même sujet. Mais ce sera moins exploitable par les outils de navigation décrits plus loin...
  • En l'absence de tags attachés aux pages, on va pouvoir exploiter cette structure hiérarchique pour offrir une navigation facile dans l'ensemble des documents.

Il est important de prendre le temps pour organiser la structure avant de créer les pages car la modification ultérieure du nom des pages (possible uniquement en copiant/collant le contenu de pages existantes dans de nouvelles pages) cassera inévitablement les références entre pages.

Barre de Navigation

Configuration

Il y a plusieurs façons de construire des menus de navigation. Celle décrite ici repose sur l'utilisation de la macro TracNav, utilisée dans cette page. TracNav offre plusieurs fonctionnalités intéressantes :

  • La description des menus disponibles se fait dans une page WiKi standard en utilisant des listes à puce.
  • On peut avoir plusieurs niveaux de menus en imbriquant les listes à puces
  • Lorsqu'il y a plusieurs niveaux, seule la catégorie correspondant au document courant est déroulée, ce qui permet de conserver un menu de navigation court avec un grand nombre de documents.

Pour utiliser TracNav, il suffit de placer l'appel de la macro en tête de toutes les pages qui doivent afficher le menu de navigation, généralement après le titre, avec les instructions suivantes :

         [[TracNav]]

A la première invocation, cela fait apparaître un pavé de navigation vide, avec menu Edit. Ce menu donne accès à l'édition de la page WiKi qui va contenir les menus, par défaut wiki/TOC (le mieux est de conserver ce défaut).

Dans cette page, on va trouver l'appel à TracNav et des listes à puce. Par exemple :

[[TracNav]]

 * [wiki:Doc Documentations]
   * [wiki:Doc Introduction]
   * [wiki:Doc/Apache Apache]
     * [wiki:Doc/Apache Introduction]
     * [wiki:Doc/Apache/ChangeLog Changements de Configuration]
     * [wiki:Doc/Apache/AccountMgt Gestion des Comptes]
   * [wiki:Doc/Mail Mailer]
     * [wiki:Doc/Mail Introduction]
   * [wiki:Doc/Storage Disques et Backup]
     * [wiki:Doc/Storage Introduction]
     * [wiki:Doc/Storage/DiskReplace Remplacement Disque ESA12000]
   * [wiki:Doc/Trac Trac]
     * [wiki:Doc/Trac Introduction]
     * [wiki:Doc/Trac/Configuration Configuration]
     * [wiki:Doc/Trac/ProjStruct Structuration d'un Projet]
 * Divers
   * [wiki:Divers/WikiLALGuidelines Utilisation du WiKi]
     * [wiki:Divers/WikiLALGuidelines Editer une page]

Les éléments des listes à puce peuvent être soit du texte litéral, soit des références à des pages Wiki avec la syntaxe explicite utilisée ici.

Si on visualise une page qui fait appel à TracNav mais n'est pas listée dans la page TOC, l'ensemble du menu apparait déroulé. Si la page se trouve dans le menu TOC, la partie du menu auquel elle appartient est déroulée et les autres sont repliées et transformées en lien. La partie déroulée apparaît toujours en tête.

Lorsqu'on clique sur un lien qui a des sous menus, le document associé à ce lien s'ouvre. Il faut mettre dans le menu une deuxième entrée associée au même document (mais éventuellement avec un autre texte) pour que la page correspondante soit considérée répertoriée dans le TOC. C'est la raison des répétitions comme :

 * [wiki:Doc Documentations]
   * [wiki:Doc Introduction]

Ajouter de nouvelles entrées

Pour ajouter une entrée dans le menu, il suffit de l'éditer avec le menu edit. On peut référencer une page existante mais on peut aussi nommer une nouvelle page. En effet, c'est une fonctionnalité de base de TracWiki : si on référence une page inexistance, cela donne accès à une page permettant de la créer. C'est donc souvent le moyen le plus simple de créer de nouvelles pages, en étant sûr que la référence sera correcte.

Conséquence sur l'organisation des pages

A chaque niveau de menu, il peut être intéressant d'associer un niveau de hiérarchie dans le nommage des pages. Pour chaque niveau ainsi créée, la recommandation est de créer une page portant le même nom que le niveau et qui deviendra la page d'aperçu du niveau correspondant. Voir la structuration de ce site pour des exemples.

Index des pages d'une catégorie

Dans la page d'aperçu, il peut être intéressant de donner un accès à toutes les pages de la catégorie, y compris celles qui ne seraient pas dans le menu de navigation. Ceci est grandement facilité par l'organisation hiérarchique des pages. Il suffit d'ajouter dans la page d'aperçu un lien tel que :

         [wiki:category/TitleIndex Liste des documents]

et de créer le document correspondant (en cliquant sur la référence créée précédemment par exemple) dont une version de base est :

= Liste des Documents =
[[TracNav]]

[[TOC(titleindex,inline)]]

Cela produit une liste de toutes les pages de la catégorie, avec le titre de la page en description.

Il est aussi possible d'utiliser la macro TitleIndex au lieu de TOC. Dans ce cas, la liste ne contient que le nom des pages, sans le titre.

Table des Matières

Quand on écrit des pages un peu longues, il peut être intéressant de générer en tête de la page une table des matières à partir de la structure de la pages (les différents niveaux de titre). Cela se fait très simplement en ajoutant au début de la page (généralement après l'appel à TracNav) un appel à la macro TOC. Par exemple :

[[TOC(inline)]]

Le paramètre inline indique que la table des matières doit être instérée au fil du texte et non pas dans une boite de navigation. C'est généralement plus agréable si on utilise aussi TracNav.

Pour un exemple, éditer cette page.

La macro TOC permet aussi de faire la table des matières de une ou plusieurs autres pages, en les passant leur nom en paramètre de la macro.

Page de démarrage

En lien avec le menu de navigation, il peut être intéressant que la page de démarragedu WiKi ne soit pas celle par défaut (wiki). Pour cela il suffit de l'éditer et de remplacer son contenu par :

= Titre de la page de demarrage =

[redirect(wiki:ma/page/de/demarrage)]
Last modified 13 years ago Last modified on Dec 3, 2010, 10:55:23 AM