برنامج تعليمي بسيط حول كيفية توثيق مشروع Python الخاص بك باستخدام Sphinx و Rinohtype

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

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

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

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

Sphinx ، الذي كتبه Georg Brandl ومرخص بموجب ترخيص BSD ، تم إنشاؤه في الأصل لوثائق Python ولديه تسهيلات ممتازة لتوثيق مشاريع البرامج في مجموعة من اللغات (Sphinx-doc.org ، 2018).

Rinohtype ، يقترن Sphinx يقدم بديلا عصريا ل LaTeX. يوفر خلفية Sphinx التي تسمح بإنشاء مستندات PDF بحروف مهنية (Machiels).

في هذا البرنامج التعليمي ، سأستخدم Sphinx و Rinohtype لإنتاج ملفات وثائق HTML و PDF على التوالي لمشروع API بسيط كتبت أن يدير قائمة سجلات المعلم (Github Project Link).

  1. قم بنسخ المشروع وحذف / نقل مجلد المستندات حتى تتمكن من متابعتي في إنشاء الوثائق الجديدة.
  2. انتقل إلى الدليل الجذر للمشروع.
  3. إنشاء وتفعيل بيئة بيثون 3 الافتراضية
virtualenv -p python3 <اسم virtualenv>
المصدر <اسم virtualenv> / bin / تنشيط
هنا قمت بتسمية البيئة الافتراضية الخاصة بي

4. تثبيت جميع متطلبات المشروع

تثبيت نقطة - r requirements.txt

ملاحظة: Sphinx و Rinohtype موجودان بالفعل داخل ملف requirements.txt. إذا كنت ترغب في تثبيتها في البيئة الافتراضية للمشروع الذي تعمل عليه ، استخدم الأوامر التالية أدناه.

نقطة تثبيت أبو الهول
نقطة تثبيت rinohtype

5. قم بإنشاء دليل مستندات وقرص مضغوط في هذا الدليل.

مستندات mkdir
مستندات مؤتمر نزع السلاح

6. الإعداد أبو الهول

أبو الهول-التشغيل السريع
اتبع هذا التكوين في الوقت الحالي. يمكنك إعادة تكوين هذا لاحقًا بنفسك.استمرار الصورة السابقة

7. المصدر المفتوح / conf.py

  • تكوين المسار إلى الدليل الجذر
خطوط uncomment 15-17تغيير المسار إلى

يجب أن يشير المسار إلى الدليل الجذر للمشروع والنظر إلى بنية المشروع ، بدءًا من conf.py يجب أن نصل إلى الجذر من خلال رفع دليلين أصليين.

هيكل المشروع
  • أضف Rinohtype إلى قائمة الامتداد
"rinoh.frontend.sphinx"
  • uncomment عناصر اللاتكس
uncomment هذهيمكنك تغيير التنسيق بشكل أكبر ، فهذه هي الإعدادات الافتراضية فقط.

8. افتح index.rst وقم بتغيير المحتوى إلى ما يلي. (انقر فوق الرابط index.rst للمحتوى الكامل)

وثائق المدونة
**************************
.. toctree ::
   : الحد الأقصى: 2
   : شرح: المحتويات:

المعلم الرئيسية
===================
.. autodule :: التطبيق
   :أفراد:

تحكم المعلم
=====================
.. autodule :: teacherAPI.controller
   :أفراد:

نماذج المعلم
=================
.. autodule :: teacherAPI.models
   :أفراد:

قاعدة بيانات المعلم
===================
.. autodule :: teacherAPI.database
   :أفراد:

TeacherAPI ملء
===================
.. autodule :: teacherAPI.populate
   :أفراد:

9. قم بإنشاء ملفات وثائق HTML و PDF.

  • لا يزال داخل تشغيل دليل المستندات
جعل أتش تي أم أل
sphinx-build -b rinoh source _build / rinoh

ملاحظة التحرير [16 مارس 2019]: قد يفشل إنشاء ملف pdf إذا كان إصدار Python الخاص بك هو .73.7.0 (مرجع إصدار Github)

سينتج السطر الأول ملف HTML في docs / build / html / index.html

عرض index.htmlعرض index.html

سينتج السطر الثاني ملف PDF في docs / _build / rinoh / SimpleTeacherDataAPI.pdf

صفحة عنوان الوثائقجدول المحتوياتصفحة عينة من الوثائق

بعد تجربتي في مشاريع الفريق ، بدأت في تطوير التقدير في توثيق الشفرة ، ورغم ذلك ، لا أقول إنها المهمة الأكثر متعة ، إنها موثوقة بالتأكيد ويجب أن يمارسها المبرمجون <ينظرون إليك بنفسك>.

لمعرفة المزيد عن أبو الهول:

  • نظرة عامة - Sphinx 1.8.0+ documentation

دروس مفيدة أخرى:

  • توثيق مشروعك باستخدام Sphinx - ساعدني ذلك في فهم كيفية توثيق الكود الخاص بي باستخدام مستندات Python.
  • براندون Sphinx Tutorial - برنامج تعليمي مكثف حول استخدام Sphinx

ماشيلز ، بريشت. "Rinohtype: معالج مستندات Python - Rinohtype 0.3.1.Dev0 الوثائق." Rinohtype.readthedocs.io. N.p. ، 2016. الويب. 17 يونيو 2018.

Sphinx-doc.org. (2018). نظرة عامة - Sphinx 1.8.0+ documentation. [على الإنترنت] متاح على الموقع: http://www.sphinx-doc.org/en/master/ [تم الوصول إليه في 17 يونيو 2018].