Forum général.cherche-logiciel Génération / Gestion de documentations techniques

Posté par (page perso) .
Tags :
3
15
juin
2012

Hello !

Je suis amené dans mon travail à rédiger énormément de documentation technique.

Ce travail de documentation est parfois très répétitif, surtout au sujet de la mise en page qui doit être faite de façon homogène entre les différents documents.

Je me demandais donc s'il vous connaissiez un soft (si possible libre sous Linux), qui permettrait de rédiger les docs dans un format interne à partir duquel le soft serait capable de générer les docs sous différents formats (HTML, PDF, ODF…) mais avec toujours un format de sortie identique (et personnalisable).

En gros voici mes contraintes :
- possibilité de définir des types de paragraphes personnalisés (sortie de ligne de commande, contenu d'un fichier de configuration, etc…). Pour chacun des types, un rendu personnalisé pourra être appliqué
- possibilité d'intégrer des éléments de mise en forme (gras, italique… éventuellement des couleurs)
- au moins la possibilité d'exporter en PDF et en HTML

Un des plus serait un soft fonctionnant en ligne de commande, ce qui permettrait d'utiliser les hooks git pour la génération des documents. La procédure serait la suivante :
1. Création d'un dépôt git
2. on pousse des docs dedans
3. a chaque modification d'un des documents, le soft régénère le PDF et HTML qui sont automatiquement publiés via le serveur Web

Je suis preneur de toute proposition, merci à vous

  • # Latex ?

    Posté par (page perso) . Évalué à 2.

    Cf. le titre.

    • [^] # Re: Latex ?

      Posté par (page perso) . Évalué à 1.

      J'y ai effectivement pensé.

      Est-il possible avec les générateurs de LaTeX de personnaliser la sortie ? C'est à dire, définir des classes CSS pour les générations HTML, des styles particuliers pour les générations PDF, ou autre ?

      • [^] # Re: Latex ?

        Posté par (page perso) . Évalué à 2.

        Assurément. En fait la question qui se pose est plus : « Où trouver des modèles qui pourrait s'adapter facilement (c.-à-d. via un minimum de modifications) à mon besoin ? » Et là malheureusement, je ne sais pas vous répondre. Mes propres travaux sont tellements classiques que je me contente bien souvent des classes de bases fournies avec LaTeX.

        • [^] # Re: Latex ?

          Posté par (page perso) . Évalué à 1.

          Pas vraiment, si techniquement LaTeX est capable de répondre à mon besoin, le mettre en place ne me gêne absolument pas.. :) Je suis même plutôt pour, car au moins, je pourrais mettre en place quelque chose qui réponds à mes besoins, sans que ce soit une usine à gaz

  • # chaine éditoriale

    Posté par . Évalué à 2.

    Il y a la chaine éditoriale scenari qui est capable de répondre à une grande partie de la demande, sauf peut être l'utilisation en ligne de commande, encore que…
    http://scenari-platform.org/
    http://fr.wikipedia.org/wiki/Scenari
    Peut-être un peu lourd pour le résultat souhaité ?

    • [^] # Re: chaine éditoriale

      Posté par (page perso) . Évalué à 2.

      Effectivement, sur mon projet actuel certains utilisent scenari qui semble être un très bon outils, mais effectivement, peut-être un peu lourd pour mon besoin.

      je vais regarder du côté de LaTeX pour valider tout ça.

      Merci à vous, pour vos réponses.

    • [^] # Re: chaine éditoriale

      Posté par . Évalué à 2.

      Scenari est-il capable de supporter le scritpting ? Par exemple pour vérifier le contenu de certaines donnés, ou de récupérer une fichier généré pour l'inclure dans un document, ou encore de générer des infos (date de création, etc…) ?

      "La première sécurité est la liberté"

  • # rst

    Posté par . Évalué à 4.

    http://docutils.sourceforge.net/rst.html RestrutredText est ta solution. Ca génère quasi tout les formats, c'est agréable à écrire (un simple éditeur de texte suffit) et c'est très utilisée (notamment par python)

    • [^] # Re: rst

      Posté par . Évalué à 1.

      Je dirais même plus: Sphinx!

      • Permet de générer du HTML, PDF (via LaTeX), ePub & plus;
      • autorise la coloration syntaxique des langages reconnus par Pygments;
      • il est facile de créer un hook sur le dépôt pour appeler le Makefile générant les formats de sortie (voir la doc du système de gestion de version).
      • [^] # Re: rst

        Posté par . Évalué à 1.

        Oui, merci de ce commentaire. Notamment, penser au fait que si on a besoin de rigueur sur la typographie, latex offre beaucoup de possibilités. Tikz est également très très bon pour faire des diagrammes, je suis en train de l'utiliser et il permet beaucoup de choses.

      • [^] # Re: rst

        Posté par (page perso) . Évalué à 1.

        pluzun pour sphinx, que l'on peut combiner avec http://readthedocs.org/ pour la génération automatique à partir d'un dépôt git, hg, … Il y a la version en ligne pour les projets publiques, sinon c'est installable: https://github.com/rtfd/readthedocs.org

    • [^] # Re: rst

      Posté par . Évalué à 2.

      J'utilise rst pour ma doc et j'accroche beaucoup.

      Il y a aussi la solution wiki (dokuwiki ou autre), suivant l'usage ça peut être vraiment bien aussi.

  • # docbook

    Posté par . Évalué à 2.

    docbook : document en xml, parfait pour les docs techniques. Il y a des balises pour a peu près tout ce qui touche à l'informatique. cf http://docbook.org/tdg/en/html/docbook.html
    On peut exploser des grosses doc en plusieurs fichiers.

    Il existe des feuilles xsl pour générer pdf, html, ps etc… cf http://docbook.sourceforge.net/

    Pour la génération automatique, un makefile, jenkins ( http://jenkins-ci.org/ ) ou équivalent, et zou.

    Ah, et pour l'édition, rien ne vaut un bon vieux emacs avec le mode nxml

    • [^] # Re: docbook

      Posté par (page perso) . Évalué à 2. Dernière modification le 15/06/12 à 21:40.

      J'abonde pour docbook.
      Un contributeur l'avait proposé pour générer la doc' de notre wiki en différents formats : http://faq.eagle-usb.org/wakka.php?wiki=DocBook

      puis l'avait mis en œuvre sur le principe

      • plusieurs page wiki pour chaque contenu
      • une page de synthèse (menu)

      cf. http://faq.eagle-usb.org/wakka.php?wiki=DocFaqEagleFr

      un résultat en xml http://faq.eagle-usb.org/eagle-faq.php?page=DocBook2Fr reprenant les différents items de la faq

      • [^] # Re: docbook

        Posté par . Évalué à 2.

        Je ne sais pas mais j'ai un a priori, je me demande si c'est bien raisonnable d'écrire du xml à la main ?

        • [^] # Re: docbook

          Posté par (page perso) . Évalué à 2.

          je n'ai sans doute pas été assez clair, mais l'objet c'était de faire
          syntaxe wiki => docbook => pleins de formats (HTML, PDF…)

        • [^] # Re: docbook

          Posté par . Évalué à 1.

          Avec le manuel de référence pas loin, on s'en sort assez vite. J'utilise Emacs pour mes docs, avec autocompletion et validation, et ça reste acceptable (ie pas pire que d'écrire dans n'importe quel langage, eg Latex, tout s'apprend…)

          J'avais regardé à une époque du coté d'éditeurs plus graphiques, comme XMLMind : au final autant de raccourcis et de commandes à apprendre - alors que quand on utilise emacs pour coder, un bon nombre d'automatismes sont réutilisables directement. L'autre reproche est qu'on est trop accaparé par la structure, et pas par le contenu : mieux vaut taper au kilomètre et rajouter les tags après plutôt que se poser trop vite des questions sur la mise en page.

  • # On a le choix !

    Posté par (page perso) . Évalué à 1.

    Merci à tous pour vos réponses !

    Je vais étudier chacunes de vos solutions !

    je vous communiquerai le choix que j'ai fait… Merci !

  • # Et une autre qui à l'air sympa

    Posté par (page perso) . Évalué à 2.

    Elle fait même la gestion des fameux requirement

    Tuleap

    http://tuleap.developpez.com/tutoriels/presentation-tuleap/

Suivre le flux des commentaires

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