AsciiDoc 및 Knitr을 사용한 루비 알고리즘 문서화

게시 됨: 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)

단 두 줄로 몇 가지 예시 데이터를 읽고 내 독점 점수를 사용하여 점수를 계산했습니다. R은 이 작업을 수행하고 기본 설치로 플롯을 표시할 수 있지만 Ruby 또는 Python과 같은 언어는 더 많은 코드와 추가 패키지를 설치해야 합니다.

알고리즘 문서화

채점 시스템을 만든 후 곧바로 코드를 작성할 수 있었습니다. 사실 R에서 프로토타이핑을 건너뛰고 Ruby on Rails 앱에서 직접 프로토타입을 만들 수도 있었습니다. 그러나 R의 프로토타이핑은 빠르고 기본 수학에 매우 가깝습니다. 문서를 설정하는 방법은 다음과 같습니다.

kingfisher/
- Rakefile
- doc/
  - func_spec.Radoc

제 예제 Rails 프로젝트는 kingfisher라고 하며 문서를 "doc" 폴더에 넣습니다. Asciidoctor 사이트에 이에 대한 훌륭한 문서가 많이 있으므로 AsciiDoc 구문에 대해서는 다루지 않겠습니다. 그러나 니트로 차트를 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 에 넣고 func_spec.Radoc 및 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로 Metaprogramming을 배우는 것이 좋습니다. Metaprogramming Is Even Cooler Than Its .