AsciiDocとKnitrを使用したRubyアルゴリズムのドキュメント

公開: 2022-03-11

重要なプロジェクトにはすべてドキュメントが必要であり、実際に読んで使用できるように、優れた説明やイラストさえも使用する必要があります。 エンジニアは、ビジネス上の問題を解決するためのソフトウェアを作成しますが、通常、その特定のビジネスで豊富な経験はありません。したがって、ビジネスを文書化することは、ソフトウェアを文書化することと同じくらい重要です。

事後にドキュメントを追加することもできますが、コーディングの前に機能仕様を作成することは大きな助けになります。 機能仕様は、さまざまな分野にわたるチームのすべてのメンバーの信頼できる情報源であり、実装前に高レベルの設計を強制し、無駄な労力を防ぎます。 この投稿では、プロトタイピングからサンプルのRuby on Railsプロジェクトの機能仕様を作成するまでのサンプルプロジェクトを見て、アプリが何をするのかを説明し、開発中のリファレンスとして使用します。 私の目標は、RubyプロジェクトがAsciiDocとRを使用して次のことを実行できることを示すことです。

  • Rを使用して、新しい計算やアルゴリズムなどのプロトタイプを簡単に作成できます
  • 機能仕様やその他のAsciiDocドキュメントにRの結果を簡単に表示できます
  • ドキュメントが常に最新のデータとアルゴリズムで更新されるように、ビルドプロセスに結び付けます

機能仕様は、RDocまたはYARDを使用してAPIを文書化するための代替ではありません。これは、プロジェクト内のすべての利害関係者（プログラマーと非プログラマーを問わず）の参照として使用できる重要な追加です。

プロトタイプ

私は鮭釣りが好きで、自分や他の人が釣っている魚の詳細を追跡して共有する方法が欲しいです。 また、トップユーザーを紹介するためのスコアボードも必要です。 現在、この目的で使用されるフォーラムがありますが、スコアボードを使用した構造化データの方がはるかに優れています。

Rubyでプロトタイプを作成することはできますが、Rubyはグラフ作成を最適にサポートしていないため、Rを使用します。Rを使用すると、数学や視覚化を簡単に試すことができます。プラットホーム。

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

たった2行で、いくつかのサンプルデータを読み取り、独自のスコアを使用してスコアを計算しました。 Rはこれを実行し、バニラインストールでプロットを表示できますが、RubyやPythonなどの言語では、より多くのコードと追加のパッケージをインストールする必要があります。

アルゴリズムの文書化

スコアリングシステムを作成した後、コードに直接進むことができました。 実際、Rでのプロトタイピングをスキップして、RubyonRailsアプリで直接プロトタイピングすることもできました。 ただし、Rでのプロトタイピングは高速で、基礎となる数学に非常に近いものでした。 ドキュメントの設定方法は次のとおりです。

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

私の例のRailsプロジェクトはkingfisherと呼ばれ、ドキュメントを「doc」フォルダーに入れています。 Asciidoctorサイトにはそのための優れたドキュメントがたくさんあるので、AsciiDoc構文については説明しませんが、knitrを使用してチャートをAsciiDocに貼り付ける方法は次のとおりです。

 //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

それをfunc_spec.Radocに貼り付け、knitrとAsciiDocを実行すると、ドキュメントに次のようなものが表示されます。

knitrとAsciiDocを実行した後のサンプルチャート出力。

うまくいけば、ほとんどの開発者は、釣りをした回数に応じてスコアが対数的に上がることを直感的に理解しています。 それでも、これは念のためにそれを表示するための優れた方法です。 このチャートの周りに、釣りをしない開発者がここで何が起こっているのかを理解できるように、なぜこれが望ましいのかを説明するテキストがあります。 この例は考案されたものですが、私は過去にこのタイプのプロトタイピングとドキュメントを他のプロジェクト（財務、建設見積もりなど）で使用しましたが、計算結果が必ずしも明白ではない場合があります。

スコアのプロトタイプが作成され、ドキュメントに固執するプロットができたので、あとは入力AsciiDocをある種の出力形式に変換するだけです。 Rakefileでいくつかのルールを使用して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

これで、「rake docs」を実行して、基礎となるデータやスコア計算を変更した場合でも、ドキュメントを作成して常に最新の状態に保つことができます。

その他のソリューション

Ruby on Railsに関連するものについては、ドキュメントにカスタムグラフィックが含まれているかどうかに関係なく、AsciiDocを使用してドキュメントを作成することをお勧めします。 AsciiDocは、素晴らしいマークアップ形式で書くためのRubyネイティブの方法を提供します。 そうは言っても、Railsプロジェクトのビルドプロセスを管理して結び付けるための優れたドキュメントツールは他にもあります。

SphinxはreStructuredText（これも優れたマークアップ形式）を処理し、Matplotlibからの出力を組み込むことができます。 Pythonプロジェクトの場合、これは完璧です。Sphinx+ Matplotlibは、カスタムグラフィックスを使用して優れたドキュメントを作成するPythonネイティブの方法を提供します。 ただし、Railsプロジェクトで作業している場合は、ドキュメントを作成するためだけに、個別の環境で複数の依存関係のセットを管理する必要はありません。

ドキュメントを作成するためのソリューションは他にもたくさんあります。たとえば、doxygenやLaTeXなどのプログラムでは、ビルドシステムに合わせるために多かれ少なかれ接着剤が必要になる場合があります。 LaTeXのようなシステムが必要な場合は、それを使用してください。 かなり標準的なRailsプロジェクトがあり、文書化する必要のある数学が少しある場合は、AsciiDocとRを使用してください。

結論

RubyとAsciiDocは素晴らしいチームを作り、Rを簡単に組み合わせて、ドキュメントに優れた視覚化を加えることができます。 ggplot2などのRエコシステムの任意のパッケージを投入して、ドキュメントに美しいグラフを含めることができます。

この投稿のソース資料は、GitHubリポジトリにあります。 公開時点では、そのレポは「実際の」プロジェクトを保持していませんが、将来的にはそうなる可能性があります。

Rubyとさらに一歩話をしたい場合は、 Rubyメタプログラミングを使ったメタプログラミングを学ぶことをお勧めします。