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 ǝpɐןƃu∀ nǝıɥʇʇɐW-ǝɹɹǝıԀ (site web personnel) . Évalué à 2.
Cf. le titre.
« IRAFURORBREVISESTANIMUMREGEQUINISIPARETIMPERAT » — Odes — Horace
[^] # Re: Latex ?
Posté par Thomas Bétrancourt (site web personnel) . É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 ǝpɐןƃu∀ nǝıɥʇʇɐW-ǝɹɹǝıԀ (site web personnel) . É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.
« IRAFURORBREVISESTANIMUMREGEQUINISIPARETIMPERAT » — Odes — Horace
[^] # Re: Latex ?
Posté par Thomas Bétrancourt (site web personnel) . É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
[^] # Re: Latex ?
Posté par MrBidon . Évalué à 1.
Fonce !
# chaine éditoriale
Posté par Christophe SELLIER . É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 Thomas Bétrancourt (site web personnel) . É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 Nicolas Boulay (site web personnel) . É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 coïn . É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 fero14041 . Évalué à 1.
Je dirais même plus: Sphinx!
[^] # Re: rst
Posté par lolcat . É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 saimn . É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 Adrien . É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 jigso . É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 BAud (site web personnel) . Évalué à 2. Dernière modification le 15 juin 2012 à 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
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 lolcat . É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 BAud (site web personnel) . É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 jigso . É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 Thomas Bétrancourt (site web personnel) . É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 MrBidon . É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 à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.