Dokumentacja algorytmu Ruby z AsciiDoc i Knitr

Opublikowany: 2022-03-11

Każdy nietrywialny projekt wymaga dokumentacji i musi być angażujący ze świetnymi wyjaśnieniami, a nawet ilustracjami, aby można go było przeczytać i wykorzystać. Inżynierowie tworzą oprogramowanie do rozwiązywania problemów biznesowych, zwykle bez dużego doświadczenia w tej konkretnej branży, więc dokumentowanie działalności jest tak samo ważne jak dokumentowanie oprogramowania.

Dokumentację można przypiąć po fakcie, ale uważam, że napisanie specyfikacji funkcjonalnej przed kodowaniem jest dużą pomocą. Specyfikacja funkcjonalna jest źródłem prawdy dla każdego członka zespołu w różnych dyscyplinach i wymusza projektowanie na wysokim poziomie przed wdrożeniem, zapobiegając marnowaniu wysiłku. W tym poście przejdę przez przykładowy projekt od prototypowania do napisania specyfikacji funkcjonalnej dla przykładowego projektu Ruby on Rails, aby opisać, co aplikacja ma robić i być punktem odniesienia podczas rozwoju. Moim celem jest pokazanie, że projekty Ruby mogą używać AsciiDoc i R do:

  • Łatwe prototypowanie nowych obliczeń, algorytmów itp. za pomocą R
  • Łatwo pokazuj wyniki z R w specyfikacji funkcjonalnej i innej pisemnej dokumentacji AsciiDoc
  • Powiąż go z procesem budowania, aby dokumentacja była zawsze aktualizowana o najnowsze dane i algorytmy

Specyfikacja funkcjonalna nie zastępuje dokumentacji twojego API za pomocą RDoc lub YARD – jest to istotny dodatek, który może być używany jako punkt odniesienia dla wszystkich interesariuszy (zarówno programistów, jak i nie-programistów) w projekcie.

Prototyp

Lubię łowić łososie i chcę mieć sposób dla siebie i innych, aby śledzić i dzielić się szczegółami na temat złowionych ryb. Potrzebuje również tablicy wyników, aby zaprezentować najlepszych użytkowników. W tej chwili istnieją fora używane do tego celu, ale uporządkowane dane z tablicą wyników są znacznie fajniejsze.

Mógłbym zrobić prototyp w Ruby, ale Ruby nie ma najlepszego wsparcia dla wykresów, więc zamierzam użyć R. Używanie R daje mi wiele łatwych sposobów na zabawę z matematyką i wizualizacją, i jest to cross- Platforma.

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

W zaledwie dwóch wierszach przeczytałem przykładowe dane i obliczyłem wynik, korzystając z mojego zastrzeżonego wyniku. R może to zrobić i pokazać fabułę z waniliową instalacją, podczas gdy języki takie jak Ruby lub Python będą wymagały więcej kodu i dodatkowych pakietów do zainstalowania.

Dokumentowanie algorytmu

Po stworzeniu mojego systemu punktacji mogłem przejść od razu do kodu. W rzeczywistości mogłem pominąć prototypowanie w R i po prostu prototypować bezpośrednio w mojej aplikacji Ruby on Rails. Jednak tworzenie prototypów w R było szybkie i bardzo zbliżone do podstawowej matematyki. Oto jak skonfiguruję dokumentację:

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

Mój przykładowy projekt Rails nazywa się Kingfisher i umieszczam dokumentację w folderze „doc”. Nie zamierzam omawiać składni AsciiDoc, ponieważ witryna Asciidoctor zawiera mnóstwo świetnej dokumentacji, ale oto jak wkleić wykres do AsciiDoc za pomocą narzędzia 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

Wstaw to do func_spec.Radoc , uruchom knitr i AsciiDoc, a otrzymasz coś takiego w swojej dokumentacji:

Przykładowe wyjście wykresu po uruchomieniu programu knitr i AsciiDoc.

Miejmy nadzieję, że większość programistów intuicyjnie rozumie, że wynik wzrośnie logarytmicznie wraz z liczbą połowów; mimo to jest to świetny sposób na wyświetlenie tego, aby się upewnić. Wokół tego wykresu mam tekst wyjaśniający, dlaczego jest to pożądane, aby programiści, którzy nie łowią, mogli zrozumieć, co się tutaj dzieje. Ten przykład jest wymyślony, ale używałem tego typu prototypowania i dokumentacji w przeszłości w innych projektach (np. finanse, kosztorysowanie budowy), gdzie wyniki obliczeń nie zawsze są oczywiste.

Teraz, gdy partytura jest już stworzona i mamy plan do wklejenia w dokumentacji, pozostaje tylko przekształcenie wejściowego AsciiDoc na jakiś rodzaj formatu wyjściowego. Używam kilku reguł w moim Rakefile do przekształcenia do 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

Teraz mogę uruchomić „rake docs” i uzyskać dokumentację do zbudowania i zawsze być na bieżąco, nawet jeśli zmienię dane bazowe lub obliczenia scoringowe.

Inne rozwiązania

W przypadku wszystkiego, co dotyczy Ruby on Rails, dokumentowanie za pomocą AsciiDoc jest doskonałym wyborem, niezależnie od tego, czy w dokumentacji znajdują się niestandardowe grafiki, czy nie. AsciiDoc zapewnia natywny dla Ruby sposób pisania we wspaniałym formacie znaczników. To powiedziawszy, istnieją inne świetne narzędzia do dokumentacji, którymi będzie trochę więcej do zarządzania i powiązania z procesem budowania projektu Rails.

Sphinx przetwarza reStructuredText (również ładny format znaczników) i może zawierać dane wyjściowe z Matplotlib. W przypadku projektu w Pythonie jest to idealne – Sphinx + Matplotlib zapewniają natywny dla Pythona sposób tworzenia ładnej dokumentacji z niestandardową grafiką. Jednakże, jeśli pracujesz nad projektem Rails, jest mniej niż pożądane, aby zarządzać wieloma zestawami zależności dla oddzielnego środowiska tylko po to, aby stworzyć swoją dokumentację.

Istnieje mnóstwo innych rozwiązań do tworzenia dokumentacji, w tym programy takie jak doxygen i LaTeX, które mogą wymagać mniej lub więcej kleju, aby pasowały do ​​twojego systemu kompilacji. Jeśli potrzebujesz systemu takiego jak LaTeX, użyj go; jeśli masz dość standardowy projekt Rails i po prostu masz trochę matematyki, którą należy udokumentować, użyj AsciiDoc i R.

Wniosek

Ruby i AsciiDoc tworzą świetny zespół i łatwo jest dodać R do miksu, aby tworzyć ładne wizualizacje w dokumentacji. Możesz dorzucić dowolny pakiet w ekosystemie R, taki jak ggplot2, aby uzyskać piękne wykresy w swojej dokumentacji.

Materiał źródłowy tego posta można znaleźć w jego repozytorium GitHub. W momencie publikacji to repozytorium nie zawiera „prawdziwego” projektu, ale może w przyszłości!

Jeśli chcesz porozmawiać z Ruby o krok dalej, polecam naukę Metaprogramowania z Ruby Metaprogramowanie jest jeszcze fajniejsze niż brzmi .