إن توثيق الكود البرمجي الذي نكتبه قد يبدو عملية مرهقة و مضيعة للوقت في البداية و لكن عندما نتعلم كيفية كتابة التوثيق سنرى مدى سهولته و أهميته الكبيرة في العمل على أي مشروع برمجي مهما كان كبيراً أو صغيراً, في هذه المقالة سنتعرف بشكل عام على أهمية توثيق البرمجيات التي نعمل عليها و بشكل خاص على توثيق أكواد بايثون باستخدام نمط غوغل الخاص بالتوثيق و أخيراً سنتعرف على كيفية تحويل التوثيق الذي كتبناه إلى موقع ويب صغير يسهل عملية تصفحة و البحث ضمنه.
أهمية التوثيق في تطوير البرمجيات
قبل البدء بالحديث عن التوثيق و كيفية كتابته سنتعرف على أهميته, يمكن تلخيص أهمية التوثيق في النقاط التالية:
- شرح كيفية استخدام الكود البرمجي بالنسبة للمستخدمين له: لا أحد يقوم بكتابة مكتبات برمجية كي يستخدمها بنفسه فقط, لا بد أن نقوم بكتابة مكتبة و نحاول نشرها على شبكة الإنترنت كي يقوم الآخرين باستخدامها, حتى يكون الأشخاص الآخرين قادرين على استخدام المكتبة البرمجية لا بد من وجود توثيق دقيق و شامل للمكتبة حول كيفية إستخدامها و تضمينها ضمن مشاريعهم الخاصة, من دون التوثيق لن يقوم أحد باستخدام المكتبات التي تقوم بكتابتها.
- مساعدة المطورين الآخرين للمساهمة في مشروعك: عندما تقوم ببناء مكتبة برمجية و نشرها مع الكود البرمجي الخاص بها على موقع مثل github.com أو gitlab.com من الجيد أن يقوم مطورين آخرين بالمساهمة في تطوير مكتبتك و إصلاح بعض الأخطاء التي يتم اكتشافها ضمنها, هنا يعتبر التوثيق أيضا مهم جداً لأنه يساعد المطورين لفهم عملك و بالتالي تطويره, يمكن أن تقوم أيضاً بتضمين ما يسمى دليل المساهمة Contribution Guide لمساعدة أي مطور جديد للعمل على مشروعك.
- فهم المشروع البرمجي في المستقبل: كثيراً ما نعمل على مشروع برمجي ما ثم نقوم بترك العمل معه فترة طويلة و نعود إليه في المستقبل مع وجود التوثيق للمشروع نستطيع فهم تفاصيلة المختلفة و متابعة العمل فيه بسهولة أكثر.
- تقسيم المشروع البرمجي بشكل منطقي: عندما نقوم بتوثيق المكتبة التي نعمل عليها هذا الأمر بساعد كثيراً في اختيار التقسيمات الصحيحة للمكتبة من ناحية استخدام الصفوف و ربطها بعلاقات الوراثة المختلفة و تعريف الطرائق الصحيحة.
هذه الفوائد بالإضافة لغيرها نحصل عليها من كتابة التوثيق للمشروع البرمجي الذي نعمل عليه.
توثيق مشاريع بايثون
لغة البرمجة بايثون تعتبر من اللغات عالية المستوى السهلة الإستخدام و المنتشرة بشكل واسع في مختلف المجالات البرمجية, نجدها في تطبيقات الويب, كتابة السكريبتات, تصميم الواجهات و الأهم من ذلك في تطبيقات الذكاء الصنعي و الشبكات العصبونية إلخ….
تمتلك بايثون طرق سهلة لكتابة التوثيق لأي كائن1 يتم تعريفه ضمنها و ذلك عن طريق كتابة نص متعدد الأسطر باستخدام ثلاثة إشارات اقتباس مزدوجة “”” بعد تعريف الكائن مباشرة و يمكن الوصول لهذا النص عن طريق الواصفة __doc__ للكائن المعرف.
def func(): """ Documentation for function func """ pass
التابع func المعرف أعلاه يتضمن التوثيق الذي تم إضافته بعد تعريفه للوصول لهذا التوثيق نستخدم تعليمة طباعة كما يلي
print(func.__doc__)
نستطيع إستخدام الأمر pydoc للوصول إلى التوثيق الخاص بأي ملف معرف ضمن python.
بهذه الطريقة البسيطة نستطيع إضافة توثيق لأي كود بايثون نقوم بكتابته, سنتعرف في الفقرة التالية على التنسيق المستخدم لكتابة هذا التوثيق.
تنسيق التوثيق لكود بايثون
إن كتابة التوثيق لأي كود بايثون يجب أن يخضع لقوانين خاصة حول كيفية تنسيقه من أجل توحيد التوثيق ضمن المشاريع المختلفة و تسهيل عمل أدوات توليد التوثيق المختلفة مثل sphinx لتوليد صفحات ويب تتضمن التوثيق المكتوب و تسهيل عملية البحث ضمنه.
هناك عدة تنسيقات مختلفة للتوثيق في مشاريع بايثون سنتعرف على طريقة غوغل في التنسيق.
الطريقة موصوفة ضمن هذا الرابط.
توثيق التوابع
عملية توثيق أي تابع ضمن بايثون تتم كما يلي:
def func(arg1, arg2):
"""
A brief description of func that ends with dot.
Here we describe the function in more details and how it can be used
Args:
arg1 (type1): Describe arg1
arg2 (type2): Describe arg2
Returns:
type: Describe the return value
Raises:
Exception: When this exception is raised
"""
pass
في الكود السابق نلاحظ الأقسام التالية:
- وصف قصير للتابع ضمن السطر الأول, ينتهي هذا السطر بنقطة.
- سطر فارغ ثم نضع وصف أطول للتابع و كيفية القيام باستدعائه و المزيد من المعلومات عنه.
- سطر فارغ نضع الوسطاء الخاصين بالتابع بين قوسين نضع نوع الوسيط ثم نضع شرح عنه.
- سطر فارغ ثم نضع نوع القيمة المعادة و وصف لها.
- سطر فارغ ثم نضع جميع الإستثنائات التي يمكن أن يسببها التابع.
توثيق الصفوف
يتم توثيق أي صف كما يلي:
class Example(object):
"""
A summary for the class
A description for the class
Attributes:
attr1 (type1): descrption of attr1
"""
pass
نلاحظ أن التوثيق هنا يشبه توثيق التوابع نستخدم Attributes لتوثيق الواصفات العامة للصف كما نوثق وسطاء التابع.
توثيق ملفات بايثون
هنا نقصد بالملفات ما يسمى modules ضمن لغة بايثون, نضع التوثيق ضمن بداية الملف كما يلي:
""" A summary of the module. A description of the module. Example: Here we give examples for how the module will be used, we can include shell sessions $ python example.py Attributes: module_level_attr (type): Describe the attribute here Todo: * Include Todos for the module """
نلاحظ هنا وجود قسم خاص بأمثلة عن كيفية استخدام الملف و قسم خاص بقائمة todo للملف مع شرح لجميع المتحولات المعرفة ضمن الملف مباشرة.
الآن بعد أن تعرفنا على كيفية تنسيق التوثيق في مشاريع بايثون سنتعرف على كيفية استخدام sphinx لتوليد موقع ويب ثابت يتضمن التوثيق ضمنه مع إمكانية البحث ضمنه.
استخدام sphinx لتوليد موقع ويب للتوثيق
الآن بعد كتابة التوثيق ضمن الكود لا بد من تجميع هذا التوثيق ضمن ملف واحد أو ضمن موقع ما من أجل عرضه و سهولة البحث ضمنه من دون طريقة لعرضه لن يكون هناك أي فائدة من كتابته, يعتبر sphinx من الأدوات المستخدمة لتحويل التوثيق المكتوب إلى ملف أو موقع ويب لعرضه.
تنزيل sphinx
يجب أولاً تنزيل بايثون من الموقع الرسمي الخاص بها ثم نقوم بتنزيل sphinx عن طريق تنفيذ الأمر التالي ضمن سطر الأوامر
pip install -U sphinx
تحضير مشروع sphinx
بعد أن قمنا بكتابة التوثيق ضمن الكود البرمجي الآن نحتاج إلى إنشاء مشروع sphinx ضمن مجلد باسم docs ضمن نفس مجلد الكود المستخدم نقوم بتنفيذ الأمر التالي
sphinx-quickstart
و نتأكد من قول yes عند السؤال عن تضمين autodoc أم لا.
بشكل افتراضي sphinx لا تدعم توليد التوثيق عند كتابته باستخدام نمط غوغل, كما قمنا حتى الآن لذلك لا بد من تفعيل التوسيع extension المسماة napoleon من خلال إضافة sphinx.ext.napoleon إلى قائمة extensions في الملف conf.py.
ننفذ الأمر التالي لتوليد التوثيق بعد استبدال projectdir بمجلد المشروع الذي يتضمن الكود المستخدم في المشروع
sphinx-apidoc -f -o docs/source projectdir
هذا الأمر يولد التوثيق باستخدام الصيغة الخاصة ب sphinx, لتوليد توثيق عبارة عن صفحة ويب ننفذ الأمر make html ضمن مجلد docs, بعد تنفيذ هذا الأمر ندخل المجلد _build و ضمنه مجلد html مجد ضمنه ملف index.html الذي يتضمن التوثيق مع روابط تشعبيه له و إمكانية البحث ضمنه.
عندما نقوم بأي تغيير على التوثيق ضمن المشروع نعيد تنفيذ الأمر make html لتوليد صفحة الويب من جديد.
ختام
في هذه المقالة تعرفنا على أهمية كتابة التوثيق للمشروع البرمجي و كيفية كتابته باستخدام نمط غوغل لتنسيق التوثيق و أخيراً كيفية توليد موقع ويب لهذا التوثيق كي نستطيع عرضه و البحث ضمنه بسهولة.
- في لغة البرمجة بايثون يعتبر كل شيء عبارة عن كائن, المتحول هو كائن, الصف هو كائن, التابع هو كائن الخ….