Documentarea algoritmului Ruby cu AsciiDoc și Knitr

Publicat: 2022-03-11

Fiecare proiect non-trivial are nevoie de documentare și trebuie să fie captivant, cu explicații grozave și chiar ilustrații, astfel încât să fie citit și folosit efectiv. Inginerii creează software pentru a rezolva problemele de afaceri, în general fără a avea o experiență vastă în acea afacere anume, așa că documentarea afacerii este la fel de importantă ca documentarea software-ului.

Documentația poate fi fixată după fapt, dar consider că scrierea unei specificații funcționale înainte de codare este de mare ajutor. O specificație funcțională este o sursă de adevăr pentru fiecare membru al echipei din diferite discipline și forțează proiectarea la nivel înalt înainte de implementare, prevenind efortul irosit. În această postare, voi trece printr-un exemplu de proiect, de la prototipare la scrierea unei specificații funcționale pentru un exemplu de proiect Ruby on Rails, pentru a descrie ce ar trebui să facă aplicația și să fie o referință în timpul dezvoltării. Scopul meu este să arăt că proiectele Ruby pot folosi AsciiDoc și R pentru:

  • Creați cu ușurință prototipuri noi de calcule, algoritmi etc. folosind R
  • Afișați cu ușurință rezultatele de la R în specificația dvs. funcțională și în altă documentație scrisă AsciiDoc
  • Leagă-l în procesul de construire, astfel încât documentația să fie mereu actualizată cu cele mai recente date și algoritmi

O specificație funcțională nu este un înlocuitor pentru documentarea API-ului dvs. cu RDoc sau YARD – este o completare vitală care poate fi folosită ca referință pentru toate părțile interesate (programatori și non-programatori deopotrivă) într-un proiect.

Prototip

Îmi place pescuitul la somon și vreau o modalitate pentru mine și pentru ceilalți de a urmări și de a împărtăși detalii despre peștele pe care îl prind. De asemenea, are nevoie de un tablou de bord pentru a prezenta cei mai buni utilizatori. În acest moment există forumuri folosite în acest scop, dar datele structurate cu un tablou de bord sunt mult mai cool.

Aș putea face un prototip în Ruby, dar Ruby nu are cel mai bun suport pentru graficare, așa că voi folosi R. Folosirea R îmi oferă o mulțime de modalități ușoare de a juca cu matematica și vizualizarea, și este încrucișat. platformă.

 # 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)

În doar două rânduri, am citit câteva exemple de date și am calculat un scor folosind scorul meu proprietar. R poate face acest lucru și arăta un complot cu o instalare vanilla, în timp ce limbi precum Ruby sau Python vor necesita mai mult cod și pachete suplimentare pentru a fi instalate.

Documentarea algoritmului

După ce mi-am făcut sistemul de notare, aș putea trece direct la cod. De fapt, aș fi putut sări peste prototipul în R și să fiu prototip direct în aplicația mea Ruby on Rails. Cu toate acestea, prototiparea în R a fost rapidă și foarte aproape de matematica de bază. Iată cum voi configura documentația:

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

Exemplul meu de proiect Rails se numește kingfisher și pun documentația într-un folder „doc”. Nu voi trece peste sintaxa AsciiDoc, deoarece site-ul Asciidoctor are o grămadă de documentație grozavă pentru asta, dar iată cum să lipiți o diagramă în AsciiDoc cu 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

Introduceți asta în func_spec.Radoc , rulați knitr și AsciiDoc și veți obține ceva de genul acesta în documentația dvs.:

Exemplu de ieșire diagramă după rularea knitr și AsciiDoc.

Sperăm că majoritatea dezvoltatorilor înțeleg intuitiv că scorul va crește logaritmic odată cu numărul de pescuit; chiar și așa, aceasta este o modalitate excelentă de a afișa asta doar pentru a fi sigur. În jurul acestei diagrame, aș avea un text care explică de ce este de dorit, astfel încât dezvoltatorii care nu pescuiesc să poată înțelege ce se întâmplă aici. Acest exemplu este conceput, dar am folosit acest tip de prototipare și documentare în trecut pentru alte proiecte (de exemplu, finanțare, estimare a construcțiilor) în care rezultatele calculelor pot să nu fie întotdeauna evidente.

Acum că scorul este prototip și avem un complot de inclus în documentație, tot ce mai rămâne este să transformăm AsciiDoc de intrare într-un fel de format de ieșire. Folosesc câteva reguli în Rakefile pentru a transforma în 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

Acum pot rula „rake docs” și pot obține documentația pentru a construi și a fi mereu la zi, chiar dacă modific datele de bază sau calculul punctajului.

Alte Solutii

Pentru orice implică Ruby on Rails, documentarea cu AsciiDoc este o alegere excelentă, indiferent dacă există grafică personalizată în documentație sau nu. AsciiDoc vă oferă un mod nativ Ruby de a scrie într-un format de marcare minunat. Acestea fiind spuse, există și alte instrumente grozave de documentare care vor fi puțin mai mult de gestionat și legate de procesul dvs. de construire pentru un proiect Rails.

Sphinx procesează reStructuredText (de asemenea, un format de marcare frumos) și poate încorpora rezultatul de la Matplotlib. Pentru un proiect Python, acest lucru este perfect – Sphinx + Matplotlib vă oferă o modalitate nativă Python de a produce documentație frumoasă cu grafică personalizată. Cu toate acestea, dacă lucrați la un proiect Rails, este mai puțin de dorit să gestionați mai multe seturi de dependențe pentru un mediu separat doar pentru a vă produce documentația.

Există o mulțime de alte soluții pentru producerea documentației, inclusiv programe precum doxygen și LaTeX, care pot necesita mai mult sau mai puțin lipici pentru a se potrivi în sistemul dvs. de construcție. Dacă aveți nevoie de un sistem ca LaTeX, folosiți-l; dacă aveți un proiect Rails destul de standard și aveți doar un pic de matematică care ar trebui documentat, utilizați AsciiDoc și R.

Concluzie

Ruby și AsciiDoc formează o echipă grozavă și este ușor să introduci R în amestec pentru a face vizualizări frumoase în documentația ta. Puteți introduce orice pachet din ecosistemul R, cum ar fi ggplot2, pentru a obține diagrame frumoase în documentația dvs.

Materialul sursă pentru această postare poate fi găsit în depozitul său GitHub. În momentul publicării, acel repo nu deține un proiect „adevărat”, dar s-ar putea ca în viitor!

Dacă doriți să vorbiți un pas mai departe cu Ruby, vă recomand să învățați Metaprogramarea cu Ruby Metaprogramarea este chiar mai tare decât pare .