كيفية إعداد Sphinx لتوثيق كود Python الخاص بك

Sphinx هي واحدة من أكثر الأدوات شيوعًا لإنشاء التوثيق. في جميع أنحاء مجتمع Python ، يستخدم المطورون هذا البرنامج المجاني ومفتوح المصدر. يمكنه استخراج النص مباشرة من التعليمات البرمجية الخاصة بك أو ملفات markdown ثم استخدامه لإنشاء وثائق بتنسيقات مختلفة مثل النص العادي و HTML و PDF و EPUB.

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

قبل إعداد Sphinx ، ألق نظرة على ما يفعله وبعض ميزاته الرئيسية.

ما هو أبو الهول وماذا يفعل؟

كما ذكرنا ، Sphinx هو مولد توثيق. بشكل افتراضي ، يستخدم لغة الترميز reStructuredText (RST) ولكن من خلال ملحقات الطرف الثالث ، يمكنه أيضًا استخدم Markdown ، لغة ترميز النص العادي الشائعة. ثم يقوم بتحويل ملفات RST أو markdown هذه إلى HTML أو PDF أو صفحات دليل أو تنسيقات أخرى تفضلها.

بعض ميزات أبو الهول تشمل:

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

تركيب سفنكس

قبل تثبيت Sphinx ، تأكد من أن لديك تم تثبيت Python 3 في بيئة التطوير الخاصة بك. يمكنك بعد ذلك استخدام مدير حزمة النقطة لتثبيت Sphinx عن طريق تشغيل الأمر التالي في جهازك:

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

سيؤدي هذا إلى تنزيل وتثبيت Sphinx وتوابعه.

بعد التثبيت ، قم بتشغيل ما يلي في موجه الأوامر.

sphinx-build - النسخة

إذا كان كل شيء يعمل بشكل جيد ، يجب أن ترى رقم إصدار حزمة Sphinx التي قمت بتثبيتها للتو.

إنشاء مشروع أبو الهول الجديد

بمجرد تثبيت Sphinx ، انتقل إلى دليل العمل الخاص بك وقم بتشغيل الأمر sphinx-quickstart لإنشاء مشروع Sphinx جديد.

sphinx-quickstart

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

إذا قمت بإدراج محتويات الدليل الخاص بك ، فسترى أن هذا الأمر ينشئ بعض الملفات لك. يحتوي ملف conf.py على قيم التكوين ويعمل index.rst كصفحة ترحيب لوثائقك. سوف يستضيف دليل البناء الوثائق التي تم إنشاؤها ، ويستخدم Sphinx Makefile (make.bat على Windows) لإنشاء الوثائق.

كتابة التوثيق باستخدام أبو الهول

ملف index.rst في جذر الدليل الخاص بك هو الصفحة الرئيسية للتطبيق الخاص بك. لذا ، افتحه باستخدام محرر نصوص مثل VS Code- أو أي محرر كود مجاني جيد آخر—لتحريره.

يمكنك تغيير index.rst على النحو الذي تراه مناسبًا ولكن هناك شيء واحد يجب أن يحتوي عليه على الأقل هو توجيه الجذر toctree (شجرة جدول المحتويات). هذا ضروري لأنه يربط ملفات متعددة بتسلسل هرمي واحد من المستندات.

لإضافة وثائق إلى ملف index.rst ، يمكنك استخدام علامة RST.

كمثال ، ضع في اعتبارك ملف index.rst للوحدة النمطية math_utils. قد يتضمن هذا الملف لمحة موجزة عن الغرض من الوحدة وجدول محتويات يرتبط بصفحات أخرى من الوثائق.

مرحبًا بك في Math Utils
.. toctree ::
: أقصى عمق: 2
ابدء

لاستخدام هذه الوحدة ، ستحتاج إلى ما يلي:
* تثبيت بايثون.
* محرر نصوص
الرياضيات Utils

توفر الوحدة النمطية "math-utils" وظائف الرياضيات الأساسية مثل الجمع و
الطرح.

يمكنك إضافة المزيد من ملفات .rst حسب الحاجة. على سبيل المثال ، يمكنك إنشاء دليل مساهمة في ملف يُسمى Contributor.rst يحتوي على إرشادات المساهمة التالية.

دليل المساهمة
نرحب بالمساهمات في مشروعنا! فيما يلي بعض الإرشادات الخاصة بـ
المساهمة:
- تفرع من المشروع على جيثب.
- قم بإجراء التغييرات على فرع جديد.
- اكتب اختبارات للتأكد من أن التغييرات تعمل بشكل صحيح.
- إرسال طلب سحب مع التغييرات الخاصة بك.
- قم بإجراء أي تغييرات مطلوبة.
شكرا لك على المساهمة!

يمكنك بعد ذلك ربط هذا الملف من index.rst عن طريق إضافة قسم جديد إلى التوجيه toctree:

.. toctree ::
: أقصى عمق: 2
: التسمية التوضيحية: جدول المحتويات

 المساهمة

يؤدي هذا إلى إنشاء عنصر جديد يسمى المساهمة في جدول المحتويات الذي يأخذ المستخدم إلى صفحة المساهمة عند النقر فوقه.

بمجرد كتابة الوثائق ، فإن الخطوة التالية هي بنائها. هنا ، يعني إنشاء الوثائق إنشاء صفحات HTML أو دليل أو PDF من ملفات RST.

بناء التوثيق

لإنشاء التوثيق باستخدام Sphinx ، ستحتاج إلى تشغيل الأمر make html في جذر المجلد الخاص بك حيث يوجد ملف makefile.

جعل html

يجب أن تشاهد ملفات HTML في مجلد الإنشاء. إذا كانت هناك أخطاء أثناء البناء ، فسوف يعلمك Sphinx في المحطة.

لعرض الوثائق ، افتح ملف index.html في متصفحك:

يجب أن تكون قادرًا على الانتقال إلى دليل المساهمة من جدول المحتويات.

تخصيص التوثيق

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

للتوضيح ، حاول تغيير الموضوع إلى موضوع يسمى الطبيعة:

1. افتح ملف تكوين Sphinx conf.py في دليل مشروع Sphinx.
2. ابحث عن السطر الذي يحدد خيار html_theme وقم بتغييره إلى الطبيعة
3. احفظ ملف التكوين وأعد إنشاء الوثائق لمشاهدة التغييرات.

هذا ما يجب أن تبدو عليه الصفحة الرئيسية للوثائق.

إذا كنت لا تريد استخدام السمات المضمنة ، فيمكنك دائمًا استخدام موضوع Sphinx لجهة خارجية بدلاً من.

توثيق التعليمات البرمجية الخاصة بك باستخدام Docstrings

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

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