Documentation de l'algorithme Ruby avec AsciiDoc et Knitr

Chaque projet non trivial a besoin de documentation, et il doit être engageant avec de bonnes explications, et même des illustrations, afin qu'il soit réellement lu et utilisé. Les ingénieurs créent des logiciels pour résoudre les problèmes de l'entreprise, généralement sans avoir une vaste expérience dans cette entreprise particulière, donc documenter l'entreprise est tout aussi important que documenter le logiciel.

La documentation peut être ajoutée après coup, mais je trouve que la rédaction d'une spécification fonctionnelle avant le codage est d'une grande aide. Une spécification fonctionnelle est une source de vérité pour chaque membre de l'équipe dans toutes les disciplines et oblige à une conception de haut niveau avant la mise en œuvre, évitant ainsi le gaspillage d'efforts. Dans cet article, je vais passer en revue un exemple de projet allant du prototypage à la rédaction d'une spécification fonctionnelle pour un exemple de projet Ruby on Rails afin de décrire ce que l'application est censée faire et être une référence pendant le développement. Mon but est de montrer que les projets Ruby peuvent utiliser AsciiDoc et R pour :

• Prototypez facilement de nouveaux calculs, algorithmes, etc. en utilisant R
• Affichez facilement les résultats de R dans vos spécifications fonctionnelles et autres documents AsciiDoc écrits
• Liez-le au processus de construction afin que la documentation soit toujours mise à jour avec les dernières données et algorithmes

Une spécification fonctionnelle ne remplace pas la documentation de votre API avec RDoc ou YARD - c'est un ajout essentiel qui peut être utilisé comme référence pour toutes les parties prenantes (programmeurs et non programmeurs) d'un projet.

Prototype

J'aime la pêche au saumon et je veux un moyen pour moi et les autres de suivre et de partager des détails sur les poissons qu'ils attrapent. Il a également besoin d'un tableau de bord pour présenter les meilleurs utilisateurs. À l'heure actuelle, il existe des forums utilisés à cette fin, mais les données structurées avec un tableau de bord sont bien plus cool.

Je pourrais faire un prototype en Ruby, mais Ruby n'a pas le meilleur support pour les graphiques, donc je vais utiliser R. L'utilisation de R me donne beaucoup de façons simples de jouer avec les mathématiques et la visualisation, et c'est croisé. Plate-forme.

 # Read in some example data data <- read.csv("func_spec/example_user_data.csv") # Compute the score, weighted by base-10 log of number of reports score <- mean(data$Fish.Caught) * log(length(data$Date)) / log(10)

En seulement deux lignes, j'ai lu quelques exemples de données et calculé un score en utilisant mon score propriétaire. R peut le faire et afficher un tracé avec une installation vanille, tandis que des langages comme Ruby ou Python nécessiteront l'installation de plus de code et de packages supplémentaires.

Documenter l'algorithme

Après avoir créé mon système de notation, je pouvais passer directement au code. En fait, j'aurais pu ignorer le prototypage dans R et simplement prototyper directement dans mon application Ruby on Rails. Cependant, le prototypage en R était rapide et très proche des mathématiques sous-jacentes. Voici comment je vais configurer la documentation :

• kingfisher/
  • Rakefile
  • doc/
    • func_spec.Radoc

Mon exemple de projet Rails s'appelle kingfisher, et je mets la documentation dans un dossier « doc ». Je ne vais pas passer en revue la syntaxe AsciiDoc car le site Asciidoctor contient un tas d'excellentes documentations pour cela, mais voici comment coller un graphique dans l'AsciiDoc avec knitr :

 //begin.rcode freq_change, fig.asp=0.618, fig.width=12, fig.align="center" times_fished <- 1:50 plot(times_fished, 5 * log(times_fished) / log(10), ylab="User score when average 5 catches per trip", xlab="Number of fishing trips in the past 12 months") //end.rcode

Collez cela dans func_spec.Radoc , exécutez knitr et AsciiDoc, et vous obtiendrez quelque chose comme ceci dans votre documentation :

Espérons que la plupart des développeurs comprennent intuitivement que le score augmenterait de manière logarithmique avec le nombre de fois pêché ; même ainsi, c'est un excellent moyen d'afficher cela juste pour être sûr. Autour de ce tableau, j'aurais un texte expliquant pourquoi cela est souhaitable afin que les développeurs qui ne pêchent pas puissent comprendre ce qui se passe ici. Cet exemple est artificiel, mais j'ai utilisé ce type de prototypage et de documentation dans le passé pour d'autres projets (par exemple, financement, estimation de construction) où les résultats des calculs ne sont pas toujours évidents.

Maintenant que la partition est prototypée et que nous avons une intrigue à coller dans la documentation, il ne reste plus qu'à transformer l'entrée AsciiDoc en une sorte de format de sortie. J'utilise quelques règles dans mon Rakefile pour transformer en HTML :

 require 'asciidoctor' require 'pathname' task docs: %w[doc/func_spec.html] rule '.adoc' => '.Radoc' do |t| Dir.chdir(Pathname.new(t.name).dirname) do sh "R -e 'library(knitr);knit(\"#{Pathname.new(t.source).basename}\", " + "\"#{Pathname.new(t.name).basename}\")'" end end rule '.html' => '.adoc' do |t| Dir.chdir(Pathname.new(t.name).dirname) do Asciidoctor.convert_file Pathname.new(t.source).basename, backend: :html5, to_file: true, safe: :safe end end

Maintenant, je peux exécuter des «documents de rake» et obtenir la documentation à créer et être toujours à jour, même si je modifie les données sous-jacentes ou le calcul de notation.

Autres solutions

Pour tout ce qui concerne Ruby on Rails, la documentation avec AsciiDoc est un excellent choix, qu'il y ait ou non des graphiques personnalisés dans la documentation. AsciiDoc vous offre un moyen natif Ruby d'écrire dans un format de balisage merveilleux. Cela dit, il existe d'autres excellents outils de documentation qui seront un peu plus à gérer et à lier à votre processus de construction pour un projet Rails.

Sphinx traite reStructuredText (également un joli format de balisage) et peut incorporer la sortie de Matplotlib. Pour un projet Python, c'est parfait - Sphinx + Matplotlib vous donne un moyen natif Python de produire une belle documentation avec des graphiques personnalisés. Cependant, si vous travaillez sur un projet Rails, il est moins que souhaitable d'avoir à gérer plusieurs ensembles de dépendances pour un environnement distinct juste pour produire votre documentation.

Il existe des tonnes d'autres solutions pour produire de la documentation, y compris des programmes comme doxygen et LaTeX, qui peuvent nécessiter plus ou moins de colle pour s'adapter à votre système de construction. Si vous avez besoin d'un système comme LaTeX, utilisez-le ; si vous avez un projet Rails assez standard et que vous avez juste un peu de maths à documenter, utilisez AsciiDoc et R.

Conclusion

Ruby et AsciiDoc forment une excellente équipe, et il est facile de jeter R dans le mélange pour créer de belles visualisations dans votre documentation. Vous pouvez ajouter n'importe quel package de l'écosystème R, comme ggplot2, pour obtenir de beaux graphiques dans votre documentation.

Le matériel source de cet article peut être trouvé sur son dépôt GitHub. Au moment de la publication, ce référentiel ne contient pas de "vrai" projet, mais il pourrait l'être à l'avenir !

Si vous voulez parler un peu plus loin avec Ruby, je vous recommande d'apprendre la métaprogrammation avec Ruby La métaprogrammation est encore plus cool que ça en a l'air .