توثيق خوارزمية روبي مع AsciiDoc و Knitr

يحتاج كل مشروع غير مهم إلى توثيق ، ويجب أن يتعامل مع تفسيرات رائعة ، وحتى رسوم توضيحية ، حتى يتم قراءتها واستخدامها بالفعل. يصنع المهندسون برامج لحل مشاكل العمل ، بشكل عام دون خبرة واسعة في هذا العمل المعين ، لذا فإن توثيق الأعمال لا يقل أهمية عن توثيق البرنامج.

يمكن تثبيت التوثيق بعد الواقعة ، لكني أجد أن كتابة مواصفة وظيفية قبل الترميز هي مساعدة كبيرة. المواصفات الوظيفية هي مصدر الحقيقة لكل عضو في الفريق عبر التخصصات ، وتفرض تصميمًا عالي المستوى قبل التنفيذ ، مما يمنع الجهد الضائع. في هذا المنشور ، سأنتقل إلى مشروع مثال من النماذج الأولية إلى كتابة مواصفات وظيفية لمثال مشروع Ruby on Rails لوصف ما يفترض أن يفعله التطبيق ويكون مرجعًا أثناء التطوير. هدفي هو إظهار أن مشاريع Ruby يمكنها استخدام AsciiDoc و R من أجل:

• يمكنك بسهولة إنشاء نماذج أولية للحسابات والخوارزميات وما إلى ذلك باستخدام R.
• اعرض النتائج بسهولة من R في المواصفات الوظيفية وغيرها من وثائق AsciiDoc المكتوبة
• اربطها بعملية الإنشاء بحيث يتم تحديث التوثيق دائمًا بأحدث البيانات والخوارزميات

المواصفات الوظيفية ليست بديلاً لتوثيق API الخاص بك باستخدام RDoc أو YARD - إنها إضافة حيوية يمكن استخدامها كمرجع لجميع أصحاب المصلحة (المبرمجين وغير المبرمجين على حد سواء) في المشروع.

النموذج المبدئي

أحب صيد سمك السلمون ، وأريد طريقة لي وللآخرين لتتبع ومشاركة تفاصيل حول الأسماك التي يصطادونها. يحتاج أيضًا إلى لوحة نتائج لعرض أفضل المستخدمين. في الوقت الحالي ، توجد منتديات مستخدمة لهذا الغرض ، لكن البيانات المنظمة باستخدام لوحة النتائج أكثر برودة.

يمكنني عمل نموذج أولي في 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

يُطلق على مثال مشروع ريلز الخاص بي اسم kingfisher ، وأنا أضع الوثائق في مجلد "doc". لن أتطرق إلى بناء جملة AsciiDoc لأن موقع Asciidoctor يحتوي على مجموعة من الوثائق الرائعة لذلك ، ولكن إليك كيفية لصق مخطط في AsciiDoc باستخدام 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

ألصق ذلك في func_spec.Radoc ، وقم بتشغيل 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" والحصول على الوثائق اللازمة لإنشاء المستندات وتحديثها دائمًا ، حتى لو قمت بتغيير البيانات الأساسية أو حساب النقاط.

حلول أخرى

بالنسبة لأي شيء يتعلق بـ Ruby on Rails ، يعد التوثيق باستخدام AsciiDoc خيارًا رائعًا سواء كانت هناك رسومات مخصصة في الوثائق أم لا. يمنحك AsciiDoc طريقة لغة Ruby للكتابة بتنسيق ترميز رائع. ومع ذلك ، هناك أدوات توثيق رائعة أخرى ستكون أكثر قليلاً لإدارة وربط عملية البناء الخاصة بك لمشروع ريلز.

يعالج Sphinx reStructuredText (أيضًا تنسيق ترميز جيد) ويمكن أن يدمج الإخراج من Matplotlib. بالنسبة لمشروع Python ، يعد هذا مثاليًا - Sphinx + Matplotlib يمنحك طريقة لغة Python الأصلية لإنتاج وثائق رائعة برسومات مخصصة. ومع ذلك ، إذا كنت تعمل في مشروع ريلز ، فمن غير المرغوب فيه أن تضطر إلى إدارة مجموعات متعددة من التبعيات لبيئة منفصلة فقط لإنتاج وثائقك.

هناك الكثير من الحلول الأخرى لإنتاج التوثيق ، بما في ذلك برامج مثل doxygen و LaTeX ، والتي قد تتطلب غراء أكثر أو أقل لتلائم نظام البناء الخاص بك. إذا كنت بحاجة إلى نظام مثل LaTeX ، فاستخدمه ؛ إذا كان لديك مشروع ريلز قياسي إلى حد ما ولديك القليل من الرياضيات التي يجب توثيقها ، فاستخدم AsciiDoc و R.

خاتمة

يشكل Ruby و AsciiDoc فريقًا رائعًا ، ومن السهل رمي R في المزيج لعمل تصورات لطيفة في وثائقك. يمكنك طرح أي حزمة في النظام البيئي R ، مثل ggplot2 ، للحصول على مخططات جميلة في وثائقك.

يمكن العثور على مصدر المواد لهذا المنشور في GitHub repo. اعتبارًا من النشر ، لا يحمل هذا الريبو مشروعًا "حقيقيًا" ، ولكنه قد يحدث في المستقبل!

إذا كنت تريد التحدث خطوة إلى الأمام مع روبي ، فإنني أوصي بتعلم البرمجة الوصفية باستخدام Ruby Metaprogramming أكثر برودة مما يبدو .