URL: https://linuxfr.org/forums/general-cherche-logiciel/posts/generateur-de-site-statique-pour-documentation-utilisateur Title: Générateur de site statique pour documentation utilisateur Authors: Sclarckone Date: 2017年06月19日T20:07:01+02:00 License: CC By-SA Tags: Score: 1 Salut tout le monde, Je dois rédiger de la documentation utilisateur en ligne et je voudrais pour cela utiliser un générateur de site statique, pour les côtés facile à déployer, sources "lisibles" et "versionnables". Précision importante, la documentation ne s'adresse pas à des développeurs mais à des utilisateurs donc j'ai besoin de pouvoir insérer des images, des tableaux et de les mettre en forme, bref de pouvoir faire un peu de mise en page. Et bien que je connaisse un peu de HTML/CSS je ne suis pas moi-même développeur. J'ai essayé quelques outils connus mais la plupart utilisent du Markdown pour les sources, qui me semble assez pauvre au niveau de la gestion des images/tableaux. J'ai également regardé du côté d'outils permettant d'utiliser AsciiDoc ou reStructuredText (qui m'ont l'air d'avoir des possibilités plus étendues que Markdown en termes de mise en page) mais c'est pas toujours bien pris en charge (cf. mes essais ci-dessous)... Pour le moment j'ai essayé les outils suivants : * [MkDocs](http://www.mkdocs.org/) : Markdown seulement mais pas mal pour ce que j'ai testé. * [GitBook](https://toolchain.gitbook.com/) : semble parfait au premier abord et gère AsciiDoc. Pour ce dernier la doc de Gitbook renvoie vers celle d'[AsciiDoctor](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) mais en pratique j'ai eu quelques déconvenues (par ex., impossible d'aligner une image de la manière documentée ou de mettre en forme un tableau). * [Hugo](https://gohugo.io/) : essayé pour son support de reStructuredText et la documentation est très bien faite mais le support en question est plutôt bancal (ça passe par un module Python `rst2html`) et à la première tentative d'insérer une image le fichier source semble introuvable mais aucun message d'erreur affiché (à cause du fait que ça passe par le module Python j'imagine). J'avais aussi considéré à Sphinx mais ça a l'air très orienté Python et la documentation est relativement imposante au premier abord (ceci dit elle doit être complète). Bref, j'ai donc 2 grandes interrogations : * Ai-je raison de croire que des langages de markup autres que Markdown seraient plus appropriés pour produire de la documentation utilisateur ? * D'expérience avez-vous des générateurs de site statique à me conseiller pour rédiger de la documentation ? Merci!