Developpez.com - Java
X

Choisissez d'abord la catégorieensuite la rubrique :


Plug-ins

Documentation en ligne

Date de publication : 26/10/2011. Date de mise à jour : 22/12/2011.

Par Serge Bachmann
 

La commande "Help > Help Contents" affiche la documentation en ligne.
Ce document permet de développer notre propre documentation.

       Version PDF (Miroir)   Version hors-ligne (Miroir)
Viadeo Twitter Facebook Share on Google+        



1. Introduction
1-A. Spécification
1-B. Lancement de la plateforme Eclipse
1-C. Passage en perspective « Plug-in Development »
2. Initialisation du Plug-in
2-A. Création du projet
3. Construction du Plug-in
3-A. Génération de la documentation à partir d'un template
3-B. Description de la structure de la documentation
3-B-1. « Tables of contents » (les fichiers « toc »)
3-B-1-A. « toc.xml »
3-B-1-B. « tocgettingstarted.xml »
3-B-1-C. « tocreference.xml »
3-C. Schéma de la structure de la documentation
4. Visualisation de la documentation générée
5. Édition de la documentation
5-A. Renommer la documentation
5-B. Ajouter un sujet dans « getting started »
5-B-1. Création des fichiers html
5-B-2. Création du sujet Champignons
5-C. Test
6. Édition fichier « HTML »
6-A. Création « folder » Images
6-B. Édition des fichiers html
6-C. Test
7. Création plug-in
8. Conclusions
9. Licence


1. Introduction


1-A. Spécification

Créer une documentation accessible à partir de la commande :

« Help > Help Contents »


1-B. Lancement de la plateforme Eclipse

Double cliquer :ou le raccourci vers cet exécutable si vous l'avez créé dans le répertoire destiné à recevoir les « workspaces ». La plate-forme « Eclipse » est lancée:

On sélectionne le « workspace »:

Cliquer « OK », Fermer la fenêtre « Welcome »


1-C. Passage en perspective « Plug-in Development »

Faire : « Window - Open Perspective > Other... » :

Dans « Open Perspective » sélectionner « Plug-in Development »:

Cliquer « OK »

Pour simplifier le « Workbench » on ferme les vues: Outline, Task List, Error Log, Problems, Tasks, Plug-ins). Avant de fermer une vue il peut être nécessaire de la faire apparaître, dans le cas de la vue « Plug-ins » sa visualisation est longue.

On obtient:


2. Initialisation du Plug-in


2-A. Création du projet

Sélectionner « File > New > Plug-in Project »

Dans « New Plug-in Project - Plug-in Project » nommer le projet :

Cliquer « Next > ».

Dans « New Plug in Project - Content » donner le nom du provider » :

Cliquer « Finish ».


3. Construction du Plug-in


3-A. Génération de la documentation à partir d'un template

Dans le « Plugin Manifest Editor » onglet « Extensions » cliquer « Add... ». Dans « New Extension - Extension Point Selection » sélectionner l'onglet « Extension Wizard » et choisir « Help Content »

Cliquer « Next> ».

Dans « Help Table of Contents - Sample Help Table of Contents » sélectionner les éléments qui constitueront la documentation:

Cliquer « Finish ». Faire une sauvegarde

On obtient:


3-B. Description de la structure de la documentation

La documentation est construite à partir de l'extension « org.eclipse.help.toc »

Sélectionnons dans le « Plug-in Manifest Editor », l'onglet « Extension » on à :

en sélectionnant l'onglet « plugin.xml » on visualise toutes les initialisations :
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension
         point="org.eclipse.help.toc">
      <toc
            file="toc.xml"
            primary="true">
      </toc>
      <toc
            file="tocgettingstarted.xml">
      </toc>
      <toc
            file="tocreference.xml">
      </toc>
   </extension>

</plugin>
Cette extension définit les fichiers « toc »(1) de premier et de second niveau. L'attribut « file » défini le nom des fichiers « toc ». L'attribut « primary » à true indique que le fichier « toc » apparaît au premier niveau dans la structure de la documentation. Un fichier de second niveau ne sera pris en compte que s'il est référencé par un fichier de premier niveau.

Ici, « toc.xml » est de premier niveau il devra référencer "tocgettingstarted.xml" et "tocreference.xml".


3-B-1. « Tables of contents » (les fichiers « toc »)


3-B-1-A. « toc.xml »

Cet la table de premier niveau.

Double cliquer dans la vue « Package Explorer » « toc.xml » sélectionner l'onglet « Definition » :

Si on sélectionne l'onglet « Source » on visualise la totalité de la définition de la table :
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toclabel="Sample Table of Contents"topic="html/toc.html">
   <topiclabel="Getting Started">
      <anchorid="gettingstarted"/>
   </topic>
   <topiclabel="Reference">
      <anchorid="reference"/>
   </topic>
</toc>
L'attribut « label » spécifie le texte visualisé dans la liste des sujets (« topics »).

L'attribut « topic » spécifie le texte qui est visualisé si le sujet est sélectionné.

La documentation est ici construite dans une démarche « bottom-up ». dans ce cas le fichier « toc » défini les points d'ancrage ou s'accrocheront d'autre fichiers « toc ». Deux points d'ancrage sont définis "gettingstarted" et "reference".


3-B-1-B. « tocgettingstarted.xml »

Double cliquer dans la vue « Package Explorer » « tocgettingstarted.xml » sélectionner l'onglet « Definition » :

Si on sélectionne l'onglet « Source » on visualise la totalité de la définition de « Getting Started » :
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toclabel="Getting Started"link_to="toc.xml#gettingstarted">
    <topiclabel="Main Topic" href="html/gettingstarted/maintopic.html">
        <topiclabel="Sub Topic"href="html/gettingstarted/subtopic.html"/>
    </topic>
    <topiclabel="Main Topic 2">
        <topiclabel="Sub Topic 2"href="html/gettingstarted/subtopic2.html"/>
    </topic>
</toc>
L'attribut « link to » accroche ce fichier à l'ancre "gettingstarted" du fichier "toc.xml".

Puis on défini deux sujets. A chaque sujet est associé un label et un fichier « html ».


3-B-1-C. « tocreference.xml »

Si on sélectionne l'onglet « Source » on visualise la totalité de la définition de « Reference » :
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toclabel="Reference"link_to="toc.xml#reference">
    <topiclabel="Main Topic" href="html/reference/maintopic.html">
        <topiclabel="Sub Topic"href="html/reference/subtopic.html"/>
    </topic>
    <topiclabel="Main Topic 2">
        <topiclabel="Sub Topic 2"href="html/reference/subtopic2.html"/>
    </topic>
</toc>
Comme pour la table précédente, l'attribut « link to » accroche ce fichier à l'ancre "reference" du fichier "toc.xml".


3-C. Schéma de la structure de la documentation

L'organisation globale de la documentation est illustrée par la figure ci-dessous:


4. Visualisation de la documentation générée

Faire un clic droit sur le projet « org.eclipse.helpProject » et sélectionner « Run As > Run Configuration... ».

Dans «Run configuration - Create, manage, and run configurations » double cliquer « Eclipse Application ». Une nouvelle configuration est créée, la nommer « DocEnLigne », cliquer « Apply » :

Cliquer « Run ». Une nouvelle plate-forme Eclipse est lancée.

Sélectionner « Help > Help Contents »:

La documentation « Sample Table of Contents » est visualisée :

Vous pouvez naviguer dans cette documentation :

et par exemple sélectionner « Main Topic 2 » dans « Contents » :


5. Édition de la documentation


5-A. Renommer la documentation

Double cliquer dans la vue « Package Explorer » « toc.xml ». Dans « Book Details » renommer la documentation :

Faire une sauvegarde.


5-B. Ajouter un sujet dans « getting started »

On va ajouter un nouveau sujet à « Getting Started »:


5-B-1. Création des fichiers html

Faire un clic droit sur « html/gettingstarted » et sélectionner la commande « New > File ». Nommer le fichier « Champignons.html »

Cliquer « Finish » le fichier est créé :

Ouvrir le fichier avec l'éditeur « Text Editor » :

l'éditer :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <title>LesChampignons</title>
</head>

<body>
<h1>Leschampignons</h1>
Une classification simpliste d'un non spécialiste.
</body>
</html>
Créer de même les autres fichiers:

Divers3_1.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <title>Divers</title>
</head>

<body>
<h1>Divers</h1>
Divers champignons.
</body>
</html>
Bolet3_2.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <title>Bolets</title>
</head>

<body>
<h1>Bolet</h1>
Pour reconnaitreunboletleretourner, 
ledessousduchapeauestcomposéde tubes juxtaposés.
</body>
</html>
BonBolet3_2_1.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <title>BonsBolets</title>
</head>

<body>
<h1>BonsBolets</h1>
C'est bon!
</body>
</html>
AutreBolet3_2_2.html:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <title>AutreBolet</title>
</head>

<body>
<h1>AutreBolet</h1>
C'est pas bon!
</body>
</html>
Faire une sauvegarde générale. On à :


5-B-2. Création du sujet Champignons

Dans la vue « Package Explorer » double cliquer « tocgettingstarted.xml ». Dans « Getting Started » on va éditer « Table of Contents ».

Faire un clic droit sur « Getting Started » et sélectionner « New > Topic »:

Initialiser « Topic Details »:

On crée un sous « topic » à champignons:

que l'on initialise dans « Topic Details »:

On fini de construire l'arborescence des sujets :

On fini de construire l'arborescence des sujets :

ce qui correspond au source:
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>

<toclabel="Getting Started"link_to="toc.xml#gettingstarted">
    <topiclabel="Main Topic" href="html/gettingstarted/maintopic.html">
        <topiclabel="Sub Topic"href="html/gettingstarted/subtopic.html"/>
    </topic>
    <topiclabel="Main Topic 2">
        <topiclabel="Sub Topic 2"href="html/gettingstarted/subtopic2.html"/>
    </topic>
 <topic href="html/gettingstarted/Champignons.html" label="Champignons">
    <topic href="html/gettingstarted/Divers3_1.html" label="Divers">
    </topic>
    <topic href="html/gettingstarted/Bolet3_2.html" label="Bolets">
       <topic href="html/gettingstarted/BonBolet3_2_1.html" label="Bons Bolets">
       </topic>
       <topic href="html/gettingstarted/AutreBolet3_2_2.html" label="Autres Bolets">
       </topic>
    </topic>
 </topic>
</toc>

5-C. Test

Lancer le test avec :

Une nouvelle plateforme Eclipse est lancé. Sélectionner « Help > Help Contents ». La fenêtre « Help - Eclipse - Plateform » contient notre documentation et en particulier le sujet « Champignons »:


6. Édition fichier « HTML »


6-A. Création « folder » Images

On crée un folder « Images ». Faire un clic droit sur « org.eclipse.helpProject » sélectionner « New > Folder »:

Dans « New Folder - Folder » nommer le folder:

On place les photos directement dans le folder « Image » en réalisant par exemple des (Copy / Paste) :


6-B. Édition des fichiers html

Ouvrir les fichiers avec « Text Editor » puis les éditer :

AutreBolets3_2_2.html :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
    <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
    <TITLE>Autre Bolet</TITLE>
    <META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0  (Win32)">
    <META NAME="CREATED" CONTENT="0;0">
    <META NAME="CHANGED" CONTENT="20100421;9332700">
</HEAD>
<BODY LANG="fr-FR" DIR="LTR">
<H1>Autre Bolet</H1>
<P><IMG SRC="../../Images/BoletPiedRouge.JPG" NAME="images1" ALIGN=LEFT WIDTH=249 HEIGHT=197 BORDER=0><BR CLEAR=LEFT>Bolet
pied Rouge</P>
</BODY>
</HTML>
BonBolet3_2_1.html :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
    <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
    <TITLE>Bons Bolets</TITLE>
    <META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0  (Win32)">
    <META NAME="CREATED" CONTENT="0;0">
    <META NAME="CHANGED" CONTENT="20100421;9391900">
</HEAD>
<BODY LANG="fr-FR" DIR="LTR">
<H1>Bons Bolets</H1>
<P><IMG SRC="../../Images/BonBolet.jpg" NAME="images1" ALIGN=LEFT WIDTH=148 HEIGHT=194 BORDER=0><BR CLEAR=LEFT>c&egrave;pe
de Bordeaux ou Boletus edulis</P>
<P>C'est bon! 
</P>
</BODY>
Divers3_1.html :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
    <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
    <TITLE>Divers </TITLE>
    <META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0  (Win32)">
    <META NAME="CREATED" CONTENT="0;0">
    <META NAME="CHANGED" CONTENT="20100421;9564000">
</HEAD>
<BODY LANG="fr-FR" DIR="LTR">
<H1>Divers</H1>
<P><IMG SRC="../../Images/AmaniteTueMouches.jpg" NAME="images1" ALIGN=LEFT WIDTH=250 HEIGHT=185 BORDER=0><BR CLEAR=LEFT>Amanite
tue mouches</P>
<P><IMG SRC="../../Images/astreeHygromtrique.jpg" NAME="images2" ALIGN=LEFT WIDTH=248 HEIGHT=186 BORDER=0><BR CLEAR=LEFT>Astr&eacute;e
hygrom&eacute;trique</P>
</BODY>
</HTML>
Faire une sauvegarde générale.


6-C. Test

Lancer le test avec :

Une nouvelle plateforme Eclipse est lancé. Sélectionner « Help > Help Contents ». La fenêtre « Help - Eclipse Platform » contient notre documentation et en particulier le sujet « Champignons » mis à jour:


7. Création plug-in

Il est nécessaire d'indiquer précisément le contenu du plug-in.

Pour cela ouvrir le « plug-in Manifest Editor » en double cliquant le fichier « META-INF / MANIFEST.MF ». Sélectionner l'onglet « Build ». Dans la zone « Binary Build » sélectionner tout ce qui est nécessaire à la construction de la documentation:

Faire une sauvegarde. Faire un clic droit sur « org.eclipse.helpProject » et sélectionner « Export... ». Dans « Export - Select » sélectionner « Plug-in Development/Deployable plug-ins and fragments ». Cliquer « Next > ». Dans « Export - Deployable plug-in and fragments » choisir le répertoire pour recevoir le plug-in:

Cliquer « Finish ». Le plug-in est créé:

Relancer Eclipse (peu importe le workspace).

Sélectionner « Help > Help Contents » la documentation s'affiche:


8. Conclusions

Comme le montre ce document il est simple de mettre en place la documentation en ligne associé à un « plug-in ». Le seul piège a éviter c'est de ne pas oublier de spécifier le contenu du « plug-in ».


9. Licence

La licence « créative commons » :


s'applique à ce document.



               Version PDF (Miroir)   Version hors-ligne (Miroir)

(1)« Toc » pour : Table of contents

Valid XHTML 1.0 TransitionalValid CSS!

Licence Creative Commons
Le contenu de cet article est rédigé par et est mis à disposition selon les termes de la Licence Creative Commons Attribution 3.0 non transposé.
Les logos Developpez.com, en-tête, pied de page, css, et look & feel de l'article sont Copyright © 2013 Developpez.com.

Responsables bénévoles de la rubrique Java : Mickael Baron - Robin56 -