Bonjour à tous,
J’espère être dans la bonne catégorie… Comme le dit le titre, je cherche actuellement quoi utiliser pour rédiger de la doc pour un outil logiciel. Je parles ici plutôt de manuels utilisateurs - avec copie d’écran, etc - pas de la doc du code. Il s’agit de produire principalement des pages html, et pouvoir en plus générer un pdf serait bien.
J’ai vu que le format docbook, basé sur XML, a l’air pas mal utilisé, et il semble correspondre à ce que je cherche (format textuel ouvert), mais j’ai du mal à trouver de comment le mettre en œuvre en pratique. Quelqu’un l’a déjà utilisé ?
Sinon, qu’utilisez-vous pour ce genre de besoin ?
Merci d’avance.
1 « J'aime »
Je n’avais jamais entendu parler de Docbook.
Le format XML est plutôt facile d’utilisation, mais je le trouve un peu trop verbeux.
Personnellement, à chaque fois que je dois écrire une documentation ou un article, je le fais avec Latex.
C’est peut être un peu compliqué à prendre en main, mais une fois l’habitude prise c’est extrêmement puissant et complet !
Merci pour cette réponse Thibault. Je suis d’accord que le XML est verbeux, mais il y a pas mal d’aide dans les éditeurs pour que ça soit plus facile.
J’ai beaucoup utilisé LaTeX (même si maintenant, j’écris plutôt en txt2tags qui génère ensuite du LaTeX), mais je trouve que la sortie HTML n’est jamais très sexy.
Il m’a semblé que l’intérêt de docbook, c’est de vraiment bien séparer le fond de la forme, mais il ne faudrait pas non plus que ça soit trop horrible à utiliser !
Au contraire, je trouve la sortie incroyablement belle et propre.
Le problème de Latex, c’est qu’il nécessite beaucoup de travail et d’apprentissage pour arriver a des résultats satisfaisants.
Voici quelques exemple de documents Latex, certains d’entre eux sont vraiment hallucinants !
Pour la sortie papier, je suis d’accord qu’on peut faire de très belles choses, et je pense être capable de faire à peu près ce que je veux avec LaTeX ;-) Je parlais plutôt de la sortie HTML… ou alors il y a des outils que je ne connais pas.
J’ai déjà utilisé LaTeX2HTML et Hevea, mais je dois dire qu’il y a longtemps, et les outils ont peut-être évolué depuis…
Je dois avouer que je n’ai jamais fait de sortie HTML avec Latex et effectivement, en regardant vite fait, les sorties n’ont pas l’air terrible.
Tu devrais jeter un coup d’oeil aux différents outils listés ici (désolé la page est en anglais…).
Merci @Thibault : je vais regarder ça.
Pour l’instant, j’ai aussi trouvé Softcover : la vidéo de présentation est plutôt bluffante, et le résultat produit est assez joli. Je vais tester !
Personnellement je pense que DocBook comme Latex sont des “armes de guerre” inutiles dans un premier temps (courbe d’apprentissage longue). Leur principal avantage est la personnalisation qu’on peut obtenir sur une sortie PDF.
Je te conseillerais plutôt de commencer avec Sphinx (basé sur Python et utilisé pour la documentation officielle Python) qui utilise la syntaxe Restructured Text (RST) ou bien d’utiliser Gitbook qui utilise le Markdown. Pour Sphinx, un tutoriel en Fr est disponible. L’avantage de ces deux outils: ils font des sorties HTML et PDF sans se compliquer et supportent le multi-langue. Pour le deuxième point, je peste souvent sur le support anglo-anglais à ce sujet du genre “on a une super doc anglaise mais on a rien prévu pour les non-anglophones…”.
Contrairement au Docbook, le Markdown ou le RST de base prennent moins d’une journée d’apprentissage.
Pour finir, si tu veux toujours passer à Docbook ou Latex plus tard (si ça te parait valoir le coup), tu pourras toujours utiliser Pandoc (un utilitaire en ligne de commande pour convertir entre différent formats dont Markdown, Latex, Docbook, RST,…
Si tu dois piocher des idées sur la documentation, la manière de rédiger le contenu, les outils pour la produire, la référence pour moi est http://conf.writethedocs.org
Merci @ThomasG77. Tous tes liens m’ont l’air intéressants. Je n’ai pas de problèmes de langue, car de toute façon, c’est pour faire de la doc en anglais. Je pense quand même que je vais tester Pandoc car j’ai déjà pas mal de matériel au format txt2tags (que j’utilise depuis pas mal d’années pour générer du LaTeX). Mais Sphinx et Gitbook ont l’air bien aussi.
Merci aussi @benjamin_bnds. Readme.io a l’air intéressant, mais il ne correspond pas à mon besoin car je souhaite avoir des documents autonomes, et garder la maitrises des outils que j’utilise, et non hébergés dans un nuage.
Je me sers aussi de Pandoc, (y comprit pour ma page personnelle) qui en plus d’être écrit en Haskell me permet de faire mes slides, mes documents techniques et avancer dans mon livre avec une jolie mise en page (LaTeX oblige :P) directement.
Pour la génération de documentation, j’utilise en général ce que m’offre le langage que j’utilise (ou j’écris rapidement un générateur de Markdown/HTML à la volée).
Personnellement, je me sers également de pandoc pour générer du docx à partir de documents html ou rst. Pour la génération de PDF il s’appuie sur latex je crois. Il est nécessaire de se farcir le langage pour faire les templates. Latex, je suis de moins en moins fan…
On parle aussi beaucoup d’asciidoc et asciidoctor mais je n’ai pas essayé.
Merci @Nuki et @romain_touze. J’ai regardé Pandoc, mais il n’offre pas non plus le découpage en plusieurs page html. Ça ne me dérange pas d’écrire des feuilles de style LaTeX, mais ce n’est pas vraiment adapté à une sortie HTML, surtout si on veut plusieurs pages.
Je suis en train de tester Sphinx, recommandé plus haut par @ThomasG77 , et pour l’instant, ça a l’air de bien me convenir. On peut faire un joli document pdf à l’aide de styles LaTeX, et configurer le HTML à partir de thèmes existants que l’on peut facilement modifier. Le langage RST a l’air bien plus riche que les autres markups que j’ai utilisés, mais quand même assez léger à utiliser.
Merci encore pour vos conseils à tous.
J’ai découvert Mkdocs il y a peu et c’est vraiment pas mal. La documentation est écrite en Markdown dans une structure de fichier classique.
Pour avoir une idée de ce que ça peut donner, j’ai réalisé cette documentation avec Mkdocs, et voici les fichiers sources.
S’est peut-être en dehors de ton scope, mais si tu utilises GitHub, tu peux très facilement intégrer la génération de la documentation dans une intégration continue avec ReadTheDocs (qui supporte Sphynx et Mkdocs dans une moindre mesure).
Par rapport à Sphynx (qui utilise RST), Mkdocs utilise Markdown et est plus simple à mettre en oeuvre.
Sinon, tu as une grosse liste d’outil de documentations sur cette page.
1 « J'aime »
Merci @Toilal. Je n’ai pas trop le temps de regarder ça maintenant, mais en effet, ta doc a une bonne tête, et la liste que tu indiques est impressionnante ! Je garde ça sous le coude pour regarder quand j’aurai un moment.
Pour l’instant, Sphinx me convient bien finalement.
Après avoir expérimenté sur 10 ans : Docbook, Latex, RST, Sphinx, j’ai fini dernièrement par faire simplement du HTML + CSS + plugins JS, c’est ce qui me donne le plus de flexibilité au final.
Avec PhantomJS je peux même faire une version PDF.
Markdown, HTML, CSS. Simple et flexible, je me suis fais un générateur c’est plutôt pratique.
Pandoc pour changer de format.
@Toilal j’aime bien le rendu, tu utilises un template Mkdocs ?
Oui, c’est le theme spacelab, mais il y’en a d’autres.
Ok Merci :)