24 septembre 2021

[ad_1]

Présentation de Slate – L’outil de documentation statique de VP pour les développeurs

Par VP 5 novembre 2013 Actualités & Culture

Si vous êtes développeur, vous êtes probablement au courant des difficultés liées à la rédaction de la documentation de l’API. Les API sont ennuyeuses à documenter. Non seulement ils sont très longs et minutieusement détaillés, mais rendre un document technique aussi volumineux facile à lire et à parcourir n’est pas une tâche triviale.

Aujourd’hui, nous proposons Slate, un modèle de documentation d’API intelligent et simple que vous êtes libre d’utiliser pour documenter l’API de votre propre site Web.

nos nouveaux docs générés avec l'ardoise

Premiers pas avec l’ardoise

Dès la sortie de la boîte, Slate dispose d’une table des matières générée automatiquement et animée de manière fluide à l’extrême gauche de la page. Lorsque vous faites défiler, il affiche votre position actuelle dans le document :

la barre de navigation

Slate a également une section pour les exemples de code (avec coloration syntaxique) sur le côté droit de la page. Si votre API a des liaisons dans plusieurs langages de programmation, vous pouvez même mettre des onglets afin que les lecteurs puissent facilement basculer entre les langages :

onglets de langue des ardoises

Programmation et publication quasi indolore

La publication avec Slate est également un jeu d’enfant. Exécutez simplement une seule commande – rake publish – et Slate publiera automatiquement votre documentation sur les pages Github. Si vous n’êtes pas un type de pages Github, vous pouvez toujours utiliser rake build, et Slate vous donnera un tas de HTML statique à servir où vous le souhaitez.

La meilleure partie est que toutes ces fonctionnalités sont super faciles à utiliser. Lorsque vous écrivez un document dans Slate, vous écrivez simplement Markdown. Les descriptions des points de terminaison sont toutes Markdown. La table des matières est générée automatiquement à partir de vos en-têtes Markdown. Même les exemples de code ne sont que des blocs de code Markdown

Nous espérons qu’en open source Slate, nous pourrons vous faciliter un peu la rédaction d’une belle documentation API pour votre service Web. Visitez la source Slate sur Github pour commencer dès aujourd’hui ! Et gardez un œil sur la sortie de notre API v2, bientôt disponible sur un blog de développeurs VP près de chez vous.



[ad_2]

VP