Utiliser XWiki pour générer une documentation logicielle en PDF

Posté par  . Édité par pulkomandy, Benoît Sibaud et gUI. Modéré par Pierre Jarillon. Licence CC By‑SA.
Étiquettes :
35
1
juil.
2022
Doc

Dans le cadre d'un de nos projets chez Viveris, un client nous a demandé de mettre en place un wiki partagé pour pouvoir échanger des informations avec nous. Ils utilisent habituellement le logiciel propriétaire Confluence. Cependant, Atlassian, l'éditeur de ce logiciel, a modifié son offre commerciale et il n'est plus possible d'acheter des licences pour la version auto hébergée. Dans notre cas nous ne souhaitons pas héberger notre documentation sur des serveurs contrôlés par Atlassian.

Nous avons donc cherché d'autres solutions et notre choix s'est porté sur XWiki (LGPL 2 1). Cela fait maintenant 2 ans qu'on l'utilise, on vous explique ici ce qu'on fait avec et on fait un retour d'expérience.

Le wiki fonctionne bien et nous l'avons rempli avec plein d'informations utiles sur notre projet. Cependant nous avons rencontré quelques problèmes avec l'installation par défaut.

Il n'est pas possible d'ordonner les pages comme on veut dans la table des matières. Elles sont toujours triées par ordre alphabétique, ce qui ne convient pas forcément. Dans un premier temps nous avons contourné le problème en numérotant manuellement nos pages, mais cela pose problème dès qu'on veut insérer une nouvelle page entre deux autres.

Un autre souci est que l'export du wiki en HTML ou PDF n'est pas suffisant pour nos besoins. La version HTML ne contient pas, par exemple, les tables des matières qui sont présentes sur les pages du wiki "live". L'export PDF génère un fichier pour chaque page, ce qui n'est pas pratique pour naviguer dedans.

Dans notre cas, XWiki est maintenant utilisé pour rédiger toute la documentation utilisateur de notre logiciel, et il est important de pouvoir exporter une version figée de cette documentation avec chaque livraison du logiciel (toutes les 3 semaines, puisqu'on travaille en méthodes agiles).

Nous avons donc recruté un stagiaire pour développer une solution d'export convenant mieux à nos besoins.

Dans un premier temps nous avons essayé d'utiliser le plugin multipage-pdf-export, cependant, ce dernier n'est plus maintenu et ne fonctionne pas du tout avec les versions actuelles de XWiki. Après discussion avec les développeurs de XWiki, nous avons donc déployé l'application application-documentation qui est conçue pour cet usage. Elle est développée par l'entreprise XWiki SAS et utilisée par plusieurs de leurs clients. Le code source est disponible, mais peu documenté.

meme avec un enfant demendant à un adulte: est-ce qu'il y a une doc? L'adulte ne répond pas et prend l'enfant dans ses bras pour le consoler

Les développeurs XWiki nous ont également fourni un script (développé dans le langage Velocity qui permet d'accéder aux APIs de XWiki) permettant de générer un export PDF contenant toutes les pages de la documentation. Ce script nous a servi de base mais nous avons du le modifier pour ajouter différentes choses:

  • Gestion des pièces jointes dans les pages pour récupérer nos illustrations, schémas et captures d'écrans
  • Modification des niveaux de titres dans les pages pour avoir une numérotation cohérente
  • Personnalisation de la page de page de garde, des en-têtes et des pieds de pages pour générer un document conforme aux règles du projet

Un problème qui s'est posé est la migration des pages existantes vers l'application-documentation. En effet il ne semble pas y avoir dans XWiki de moyen de déplacer une page d'une application vers une autre. Il semble que cela poserait des problèmes dans la base de données car chaque application peut ajouter diverses données aux pages qu'elle contient, et si on déplace les pages sans y prendre garde, ces données pourraient être manquantes.

Nous avons commencé le développement d'une fonction pour importer des pages dans l'application, cependant, par manque de temps, nous n'avons pas pu la terminer. Comme pour l'instant nous utilisons XWiki sur un seul projet, nous avons décidé de recréer nos pages dans l'application et de déplacer manuellement le contenu. Pas très fun, mais il n'y a finalement qu'une centaine de pages. Pour les prochains projets il suffira de configurer le wiki dès le départ avec la bonne application pour architecturer la documentation.

Finalement, nous sommes satisfaits de l'utilisation de XWiki et de l'aide apportée par les développeurs pour l'utiliser correctement. Il est dommage que la solution mise en place dans notre cas repose sur des composants qui ne font pas partie de l'installation de base ou des greffons proposés publiquement pour XWiki. Cependant, on a quand même pu s'en sortir.

Dans le dépôt git vous pourrez trouver la documentation pour installer l'application et le script sur un XWiki. Cette documentation au format PDF est générée en utilisant l'outil développé et vous donnera une idée du résultat obtenu.

Nous allons recommander cette solution à nos collègues pour d'autres projets et peut-être aussi à nos clients qui auraient la même problématique.

Aller plus loin

  • # Merci pour le retour

    Posté par  . Évalué à 10. Dernière modification le 01 juillet 2022 à 09:47.

    Je pense qu'on s'est rencontrés aux JDLL. Merci d'être passé à notre stand :-)

    Merci pour ce retour d'expérience. C'est toujours intéressant de savoir que l'outil sur lequel on bosse est utile, et quels problèmes on peut rencontrer avec. On prend note !

    Pour la génération PDF multi page, en effet ce n'est pas une fonctionnalité de base et l'extension qui servait à ça n'est plus maintenue. Une manière classique de faire est de créer une nouvelle page et d'utiliser la macro include pour inclure les différentes pages dedans, avec des sauts de pages entre (ce qui peut se faire avec la propriété CSS break-after).

    Ça peut aussi, comme tu le mentionnes (tu sais déjà mais je développe pour les lecteurs et les lectrices du site), se scripter en Velocity, qui est effectivement un langage de template assez puissant et avec lequel on peut accéder à l'API publique d'XWiki et faire pas mal de choses. Ou en Groovy. Ça permet d'utiliser des boucles pour ne pas avoir à de payer l'inclusion manuelle de dizaines de pages si effectivement il y en a beaucoup. Ou d'automatiser, par exemple, la création de pages, ce qui peut se faire en quelques lignes :

    {{velocity}}
#set($xdoc = $xwiki.getDocument("Nom.De.La.Nouvelle.Page"))
$xdoc.setContent("Nouveau contenu")
$xdoc.save()
{{/velocity}}

    Tout ceci étant dit, j'ai partagé ton article dans le chat de l'équipe, on me souffle à l'oreille que tu pourrais être intéressé par nos derniers développements en matière d'export PDF. On te recontacte.

    Concernant le déplacement de pages, ça se fait aisément avec la fonction de renommage. Mais effectivement, si l'application stocke des métadonnées dans la page (Pour celles et ceux qui ne connaissant pas, dans XWiki, on peut définir des classes, et il est possible d'attacher des objets qui sont des instances de ces classes à des pages XWiki), ça va tout casser, un peut comme vous casseriez une application de bureau en déplaçant ses fichiers de configurations.

    J'imagine qu'une des solutions possibles pour avoir le contenu ailleurs serait là aussi d'utiliser la macro include sur la page où on veut voir le contenu, ou de le scripter en Velocity / Groovy. Mais on est d'accord, parfois, c'est tout aussi voir plus simple de le faire manuellement, surtout quand c'est une opération one-shot qui ne concerne pas un volume énorme de données.

    En tout cas il ne faut pas hésiter à nous faire d'autres retours ou nous poser des questions. On a aussi un canal #xwiki public sur Matrix (en anglais).

    • [^] # Re: Merci pour le retour

      Posté par  (site web personnel, Mastodon) . Évalué à 5.

      Je pense qu'on s'est rencontrés aux JDLL. Merci d'être passé à notre stand :-)

      En effet, c'est parfois plus facile de prendre contact sur place :)

      (c'est moi qui suis venu sur le stand aux JDLL, ensuite j'ai transmis les informations à Nicolas qui a fait le reste du travail pour faire fonctionner tout ça)

      Merci pour votre aide sur ce sujet en tout cas, ça nous a permis de mettre en place une solution satisfaisante.

  • # Petite précision sur l'offre Atlassian

    Posté par  . Évalué à 3.

    "Cependant, Atlassian, l'éditeur de ce logiciel, a modifié son offre commerciale et il n'est plus possible d'acheter des licences pour la version auto hébergée".

    Ca ne change pas grand chose au fond de l'histoire, mais afin d'être plus exact, l'éditeur a modifié son offre commerciale et il n'est plus possible d'acheter des licences pour la version auto-hergée d'entrée de gamme (server). En revanche, ceci reste possible pour la version plus évoluée (DataCenter).

    • [^] # Re: Petite précision sur l'offre Atlassian

      Posté par  (site web personnel, Mastodon) . Évalué à 5. Dernière modification le 02 juillet 2022 à 16:05.

      Oui en effet, ces offres commencent à 27000€/an pour 500 utilisateurs.

      À ce prix la, il vaut mieux embaucher quelqu'un pour contribuer à xwiki et développer les plugins nécessaires! C'est donc ce qu'on a fait.

      Et il faut aussi qu'on commence à se préoccuper du remplacement de Jira qui a eu à peu près les mêmes changements. On l'utilise encore pour l'instant parce qu'on avait déjà une license, et le support est assuré jusqu'en 2024.

      • [^] # Re: Petite précision sur l'offre Atlassian

        Posté par  . Évalué à -4.

        Tout à fait, et c'est pourquoi je précise que ça n'enlève rien au fond de la démarche.
        Toutefois, manipuler la vérité malheureusement décrédibilise le reste du discours à mon sens.
        Il suffira d'adapter que le modèle de licence change, et qu'en entrée de gamme, point de self-hosted, et tout le monde s'y retrouve.
        Essayer de rajouter du poids au point de vue manipulé en arguant qu'en plus il en sera de même avec Jira, alors que pour Jira, d'ailleurs, il en est vraiment de même : il est tout à fait possible d'avoir un Jira self-hosted, ça biaise le sujet initial que je trouvais pourtant très intéressant.
        C'est dommageable.

        C'est comme les libristes qui disent qu'il est tout à fait possible de s'approprier le code source d'un logiciel libre, et de le modifier.
        Si d'aucun oserait rétorquer qu'en pratique ce n'est quasiment pas possible de modifier linux, il n'est pas un libriste qui ne rétorquerait que ce n'est qu'une question de volonté et de moyen.
        Je pense qu'on en est pas si loin ici, si ce n'est une divergence dans le fond du modèle économique.

        On est sur LinuxFr, Xwiki c'est bien, Confluence et Jira c'est mal …

        • [^] # Re: Petite précision sur l'offre Atlassian

          Posté par  (site web personnel, Mastodon) . Évalué à 8.

          Je suis pas là pour décider ce qui est Bien ou Mal. J'ai juste oublié l'existence de l'offre data center tout simplement parce que notre wiki a environ 20 utilisateurs. Ce n'était pas volontaire, ça fait 2 ans que le choix d'utiliser xwiki est fait, je me souviens pas de tous les détails, c'est tout.

          D'autre part, j'ai dit qu'on utilisait Jira et qu'on est bien embêtés de devoir trouver autre chose, ce qui est plutôt un bon point pour Jira. Ça montre simplement un exemple de comment on peut se retrouver face au mur du jour au lendemain avec un logiciel propriétaire: la license peut changer et la solution utilisée tout simplement plus proposée par le fournisseur. Mais Atlassian fait les choses de façon correcte et nous laisse le temps de préparer notre migration tranquillement si c'est le choix qu'on fait. Et peut-être que finalement on décidera que le coût de mise en place d'un autre outil esttrop important et qu'on préfère payer Atlassian, même si c'est 27K€/an. Ce sera probablement même pas l'abonnement qui nous coûte le plus cher, et comme Jira est utilisé pour plusieurs projets dans l'entreprise, ça se justifie peut-être, en r'partissant les coûts entre les différents clients concernés.

          Et il me semble que le contenu de la dépêche n'est pas vide de critiques (constructives, j'espère) sur xwiki.

          Enfin je ne pense pas faire du bashing gratuit de logiciel propriétaire ici. Le but est juste de donner un peu de contexte sur comment on a choisi xwiki pour ce projet. D'autres entreprises et projets auront, bien évidemment, d'autres contraintes, d'autres budgets, d'autres possibilités, et je suppose que le combo "petite équipe d'une dizaine de personne + on peut pas stocker les données sur un cloud d'une autre entreprise" n'est pas si courant que ça (sinon Atlassian ferait un effort pour maintenir cette offre)

  • # ordre des pages dans la table des matières

    Posté par  (site web personnel) . Évalué à 5.

    Sur ce sujet j'utilise souvent une astuce pour que les répertoires s'affichent dans l'ordre que JE VEUX et que je puisse insérer facilement une nouvelle page. Je numérote de 10 en en 10 ou de 30 en 30… Si j'ai à insérer une page, je n'ai qu'a piocher dans les numéros disponibles. Et si jamais la tranche 30 - 40 devient pleine il me suffit de renommer la 40 en 45 pour me redonner du mou.

    Mais en 10 ans, cela ne m'est jamais arrivé.

    Ex : /mes_documents/50 - Etudes
    /mes_documents/100 - Administratif

    etc.

  • # Dokuwiki ne faisait pas l'affaire ?

    Posté par  (site web personnel) . Évalué à 2.

    Nous avons opté pour dokuwiki il y a presque 10 ans et j'ai l'impression qu'il fait tout ce dont vous aviez besoin, sans développement. Par curiosité pourquoi ne pas l'avoir retenu ?

    • [^] # Re: Dokuwiki ne faisait pas l'affaire ?

      Posté par  (site web personnel, Mastodon) . Évalué à 3. Dernière modification le 08 juillet 2022 à 22:41.

      J'utilise régulièrement Dokuwiki (dans beaucoup de structures où j'ai été) qui est une très bonne alternative mais obéit à d'autres critères de sélections. Entre autre, dans mon cas,
      - le fait qu'il y ait peu d'intervenant sur le wiki,
      - le fait qu'on voulait stocker textuellement mais pas faire du markdown (comparativement la syntaxe wiki est plus avancée /simple/cohérente/etc.)
      - le fait qu'on n'ait pas pas de traitements complexes sur les pages (en fait je n'ai eu qu'un cas où on a eu besoin d'un plugin pour ajouter des données dynamiques)

      XWiki convient bien quand on reste dans le mode de fonctionnement à la Confluence : une base de données pour stocker le contenu et un certain nombre de personnalisations dont je me garde en général : tu verras par exemple que tout le balisage wiki de blocs peut être stylé séparément (via une ligne parenthésée juste au dessus). Mais il y a aussi comme un système de templating intégré qui peut être intéressant dans certains cas : à la lecture Velocity/Groovy semble très sympa.
      Enfin, ce n'est pas du LAMP et les compétences socles ont une forte influence sur le choix de l'outil pour pouvoir le faire évoluer. Je ne vais pas choisir par exemple un truc qui nécessite PHP quand ce n'est pas la tasse de thé interne. Heureusement, le libre offre des solutions pour tous les goûts ; et eux ont trouvé leur saveur avec XWiki.

      “It is seldom that liberty of any kind is lost all at once.” ― David Hume

    • [^] # Re: Dokuwiki ne faisait pas l'affaire ?

      Posté par  (site web personnel, Mastodon) . Évalué à 2.

      J'utilise Dokuwiki pour des projets personnels et ça me semble quand même assez limité. On peut vraiment générer un export pdf, avec toutes les pages d'une section du wiki, dans le bon ordre?

      Pour moi la seule chose qui permet d'organiser les pages dans un dokuwiki, c'est de les présenter dans un certain ordre dans la sidebar, ou éventuellement on peut un peu organiser avec des namespaces.

      Je ne sais pas si la gestion des droits est aussi poussée, sur notre wiki il y a certaines pages accessibles par nos clients, certaines par des fournisseurs, et d'autres internes seulement pour nous.

      Il y a pas mal d'autres fonctionalités qu'on utilise aussi, par exemple la possibilité de faire des commentaires sur le contenu d'une page (équivalent aux commentaires dans les traitements de texte)

      Peut-être que je connaît pas assez bien dokuwiki et tous ses plugins et qu'on pourrait arriver à faire tout ça avec.

      • [^] # Re: Dokuwiki ne faisait pas l'affaire ?

        Posté par  (site web personnel, Mastodon) . Évalué à 2.

        Je te confirme que tu peux exporter les pages dans l'ordre de ton choix ; ça fonctionne un peu comme la fonctionnalité livre de wikipédia.

        Pour les droits, de base c'est comme le /etc/passwd mais tu peux brancher du LDAP. Il y a aussi la notion d'espaces et de groupes pour la gestion des droits d'accès, mais on peut aller aussi au niveau page par page. Chez un ancien client on avait bien des accès différenciés selon les équipes et les clients.

        Pour les commentaires, il y a divers plugins que j'ai jamais utilisé. Le plus usité permet de faire des pages de discussions à la wikipédia. Il y a aussi des plugins de de syntaxe et on doit pouvoir en trouver qui offre des commentaires non visibles dans le rendu. Bref il existe plein de choses mais je ne saurai quoi te conseiller. (et je ne sais pas trop comment ça fonctionne dans les traitements de texte pour pouvoir comparer et conseiller.)

        “It is seldom that liberty of any kind is lost all at once.” ― David Hume

        • [^] # Re: Dokuwiki ne faisait pas l'affaire ?

          Posté par  (site web personnel, Mastodon) . Évalué à 2.

          (et je ne sais pas trop comment ça fonctionne dans les traitements de texte pour pouvoir comparer et conseiller.)

          On peut sélectionner une partie du texte (mot, paragraphe, …) et appuyer sur un bouton "commentaire". Les commentaires s'affichent alors à côté de la page dans des "bulles", associé au texte surligné. On peut ensuite modifier le document et marquer le commentaire comme résolu.

          Pour les traitements de texte, on a un outil qui à partir de ça peut nous générer un fichier tableur avec tous les commentaires (indiquant le numéro de page et de paragraphe), et qui peut être utilisé comme fiche de relecture, pour vérifier dans une version suivante du document si les modifications ont bien été faites.

          Pour XWiki, on a installé un plugin de commentaires mais on a pas encore mis en place la partie "fiche de relecture" pour l'instant. Ce n'est peut-être pas nécessaire dans le projet sur lequel on utilise XWiki actuellement, ça le sera peut-être pour d'autres clients qui sont beaucoup plus stricts sur le processus de relecture et de validation de documents.

  • # Même problématique : Sortir de Confluence Atlassian

    Posté par  (site web personnel) . Évalué à 5.

    Bonjour

    Réactivation du sujet car je suis dans la même problématique : sortir de confluence
    - trop cher pour une petite équipe
    - difficile de stocker des informations "sensibles" sur le cloud

    Après quelques recherches Xwiki peut effectivement remplacer Confluence et même aller plus loin

    Confluence est un bon produit, d'ailleurs atlassian s'en est aperçu et a augmenté le tarif en conséquence … ou comment flinguer un bon produit commercialement

    XWiki est un bon produit aussi, pour être honnête je ne le connaissais pas ou peu il y a quelques jours, et il m'a agréablement surpris
    Il demande cependant un peu d'investissement (confluence aussi) pour le maitriser mais pour l'instant je ne suis pas déçu.

    J'ai pu effectuer des tests et il rempli quasiment toutes les cases que je cherchais pour mes humbles besoins :

    • une recherche efficace (y compris dans les PJ testé sur PDF ODT DOCX)
    • Des documents modèles (template) pratique quand on a pas de mémoire …
    • Gestion simple de l'arborescence ( des pages "répertoires" )
    • Gestion des droits par utilisateur (en gros rédacteur / lecteur )

    Mais aussi

    • La possibilité de copier coller des images directement
    • La gestion des mots clés (tags)
    • Un export PDF propre

    Et j'ai tout trouvé dans XWIKI parfois mieux que dans confluence (exemple sur la presonnalisation de l'export PDF) et même si il y a des différences cela ne justifie pas la différence de cout avec confluence

    Son installation est simple et bien documentée

    Et le seul reproche que je puisse faire est de ne pas avoir trouvé de tuto "from scratch" ou de "xwiki pour les nuls"

    Par exemple on partant d'un xwiki vide … vous ne pouvez rien faire … même pas l'administrer

    Il faut passer par les extensions (et il y en a beaucoup) pour un béotien c'est pas évident et c'est difficile à deviner

    Idem pour le coté programmation et dev de XWiki, on doit pouvoir fair beaucoup de choses, la ou confluence apparait comme "fermé"

    Bref Xwiki c'est vraiment bien, en 2 jours il m'apparaît comme une solution viable et économique et je vais certainement étudier le coté 'payant' pour du support et certaines extensions pour voir si elles le méritent .

    XWiki est le genre produit qui mérite de l'investissement car il offre beaucoup, et même trop de choses (ce qui est bien aussi … ) mais cela perturbe au début

    Après il faut trouver le temps …

Suivre le flux des commentaires

Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.