バックエンド

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

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

事後にドキュメントを追加することもできますが、コーディングの前に機能仕様を書くことは大きな助けになると思います。機能仕様は、さまざまな分野にわたるチームのすべてのメンバーの信頼できる情報源であり、実装前に高レベルの設計を強制し、無駄な労力を防ぎます。この投稿では、プロトタイピングから執筆までのサンプルプロジェクトについて説明します。機能仕様たとえば、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でのプロトタイピングをスキップして、Ruby onRailsアプリで直接プロトタイピングすることもできました。ただし、Rでのプロトタイピングは高速で、基礎となる数学に非常に近いものでした。ドキュメントの設定方法は次のとおりです。

Uber vs lyft2017の運転

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プロジェクトのビルドプロセスを管理して結び付けるための優れたドキュメントツールは他にもあります。

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

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