ما هو MkDocs؟ كيفية تثبيت واستخدام ونشر MkDocs

هل تريد إنشاء مستندات API أنيقة واحترافية دون عناء الأدوات المعقدة؟ قل مرحباً لـ MkDocs، وهو مولد مواقع ثابتة سريع وبسيط يحول ملفات Markdown الخاصة بك إلى مواقع توثيق رائعة. لقد كنت أستخدم MkDocs لإنشاء مستندات API، وصدقني - إنه سهل للمبتدئين والمحترفين على حد سواء. في هذا الدليل للمبتدئين، سأشرح لك ما هو MkDocs، وكيفية تثبيته، واستخدامه لبناء توثيق API، ونشره على GitHub Pages، وكل ذلك بناءً على الخطوات الرسمية. بالإضافة إلى ذلك، سأشير بسرعة إلى توثيق APIdog كبديل أكثر تطوراً. هل أنت مستعد لجعل مستندات API الخاصة بك تتألق؟ هيا بنا نتعمق!

زر

ما هو MkDocs؟ مقدمة سريعة

MkDocs هو مولد مواقع ثابتة مفتوح المصدر مصمم لإنشاء توثيق للمشاريع وواجهات API. تكتب المحتوى الخاص بك بصيغة Markdown - وهي صيغة خفيفة الوزن ومستندة إلى النص - ويقوم MkDocs بتحويلها إلى موقع HTML ثابت وحديث مع ملاحة وبحث ومظاهر قابلة للتخصيص، دون الحاجة إلى قاعدة بيانات أو سكربتات من جانب الخادم. إنه مثالي لتوثيق API لأنه بسيط، ويدعم Markdown لسهولة إنشاء المحتوى، ويولد ملفات ثابتة يمكنك استضافتها في أي مكان، مثل GitHub Pages أو Read the Docs. يشيد المطورون بسرعته وسهولته، ومجتمع MkDocs على GitHub مليء بالمكونات الإضافية والمظاهر لتجميله. سواء كنت توثق واجهة REST API أو حزمة Python، فإن MkDocs يحافظ على الأمور نظيفة وسهلة الاستخدام. هيا بنا نقوم بإعداده!

إعداد بيئتك لـ MkDocs

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

التحقق من المتطلبات الأساسية: ستحتاج إلى تثبيت بعض الأدوات:

• Python: الإصدار 3.7 أو أعلى (توقف MkDocs عن دعم Python 2). قم بتشغيل python --version في الطرفية الخاصة بك. إذا كان مفقوداً أو قديماً، قم بتنزيله من python.org. على نظام Windows، تأكد من إضافة Python إلى PATH أثناء التثبيت - حدد المربع في المثبت.
• pip: مدير حزم Python، وعادة ما يكون مضمناً مع Python 3.4+. تحقق منه باستخدام pip --version. إذا كان مفقوداً، قم بتنزيل get-pip.py من الويب وقم بتشغيل python get-pip.py.
• Git: اختياري للنشر على GitHub Pages. تحقق منه باستخدام git --version. قم بتثبيته من git-scm.com إذا لزم الأمر.

هل ينقصك شيء؟ قم بتثبيته الآن لتجنب المشاكل.

إنشاء مجلد مشروع: دعنا نحافظ على الأمور مرتبة بإنشاء مجلد مخصص لمشروع MkDocs الخاص بك:

mkdir mkdocs-api-docs
cd mkdocs-api-docs

سيحتوي هذا المجلد على ملفات MkDocs الخاصة بك، و cd ينقلك إليه، جاهزاً للعمل.

إعداد بيئة افتراضية: لتجنب تعارض الحزم، قم بإنشاء بيئة Python افتراضية:

python -m venv venv

قم بتنشيطها:

• Mac/Linux: source venv/bin/activate
• Windows: venv\Scripts\activate

سترى (venv) في الطرفية الخاصة بك، مما يعني أنك في بيئة Python نظيفة. هذا يعزل تبعيات MkDocs، مما يحافظ على نظامك مرتباً.

تثبيت MkDocs

الآن، دعنا نثبت MkDocs ونجعله جاهزاً لبناء توثيق API الخاص بك. هذا سريع ومباشر.

تثبيت MkDocs: مع تنشيط البيئة الافتراضية، قم بتشغيل:

pip install mkdocs

يقوم هذا بسحب MkDocs من PyPI وتثبيته. قد يستغرق الأمر لحظة لتنزيل التبعيات مثل Markdown و Pygments.

التحقق من التثبيت: تحقق من تثبيت MkDocs بشكل صحيح:

mkdocs --version

يجب أن ترى شيئاً مثل mkdocs, version 1.6.1 (أو أحدث). إذا فشل، تأكد من تحديث pip (pip install --upgrade pip) أو أن Python موجود في PATH الخاص بك.

تثبيت مظهر (اختياري): يأتي MkDocs مع مظاهر أساسية (readthedocs & mkdocs)، لكن مظهر Material for MkDocs هو المفضل لدى الكثيرين لمظهره الحديث. قم بتثبيته:

pip install mkdocs-material

يضيف هذا مظهراً مصقولاً وقابلاً للتخصيص مثالياً لتوثيق API. سنستخدمه لاحقاً لجعل موقعك يبدو رائعاً.

إنشاء واستخدام مشروع MkDocs الخاص بك

حان الوقت لإنشاء مشروع MkDocs الخاص بك وبناء بعض توثيق API! سنقوم بإعداد موقع بسيط لتوثيق واجهة REST API خيالية، مع صفحة رئيسية وصفحة نقاط نهاية.

تهيئة مشروع جديد: في مجلد mkdocs-api-docs الخاص بك (مع تنشيط البيئة الافتراضية)، قم بإنشاء مشروع MkDocs جديد:

mkdocs new .

يقوم هذا بإنشاء:

• mkdocs.yml: ملف التكوين لموقعك.
• docs/: مجلد يحتوي على ملف index.md، الصفحة الرئيسية الافتراضية.

مجلد docs/ هو المكان الذي تضع فيه ملفات Markdown الخاصة بك، و index.md هو نقطة الدخول لموقعك.

تحرير ملف التكوين: افتح mkdocs.yml في محرر نصوص (مثل VS Code باستخدام code .). قم بتحديثه لتعيين اسم الموقع، المظهر، والملاحة لتوثيق API الخاص بك:

site_name: My API Documentation
theme:
  name: material
nav:
  - Home: index.md
  - Endpoints: endpoints.md

يقوم هذا بتعيين اسم الموقع، وتطبيق مظهر Material (إذا كان مثبتاً)، وتحديد قائمة ملاحة بصفحتين: "Home" (index.md) و "Endpoints" (endpoints.md). احفظ الملف.

كتابة توثيق API الخاص بك: دعنا ننشئ محتوى لتوثيق API الخاص بك:

تحرير docs/index.md: استبدل محتوياته بـ:

# مرحباً بك في توثيق API الخاص بي

هذا هو توثيق واجهة REST API الرائعة الخاصة بنا. استخدم شريط الملاحة لاستكشاف نقاط النهاية والبدء!

إنشاء docs/endpoints.md: أضف ملفاً جديداً في مجلد docs/ باسم endpoints.md يحتوي على:

# نقاط نهاية API

## GET /users

يسترجع قائمة بالمستخدمين.

**مثال على الطلب**:
```bash
curl -X GET https://api.example.com/users

الاستجابة:

[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]

تحدد ملفات Markdown هذه الصفحة الرئيسية لـ API ونقطة نهاية نموذجية، باستخدام كتل التعليمات البرمجية للوضوح. لا تتردد في إضافة المزيد من نقاط النهاية أو التفاصيل!

معاينة موقعك: ابدأ خادم تطوير MkDocs لرؤية مستنداتك مباشرة:

mkdocs serve

يقوم هذا ببناء موقعك واستضافته على http://127.0.0.1:8000/. افتح هذا العنوان في متصفحك، وسترى توثيق API الخاص بك مع شريط ملاحة، وبحث، وتصميم مظهر Material الأنيق (إذا كان مثبتاً). يقوم الخادم بإعادة التحميل تلقائياً عند تحرير ملفات mkdocs.yml أو Markdown، لذا قم بالتعديل وشاهد التغييرات مباشرة!

لقد اختبرت هذا الإعداد، وبدا توثيق API الخاص بي احترافياً في أقل من 10 دقائق - عملت الملاحة، ووجد البحث تفاصيل نقطة النهاية الخاصة بي فوراً. إذا لم يبدأ الخادم، تأكد من أن المنفذ 8000. متاح أو أن mkdocs مثبت بشكل صحيح.

نشر موقع MkDocs الخاص بك

توثيق API الخاص بك يبدو رائعاً محلياً - الآن دعنا نشاركه مع العالم عن طريق نشره على GitHub Pages، وهو خيار استضافة مجاني.

إنشاء مستودع Git: قم بتهيئة مستودع Git في مجلد mkdocs-api-docs الخاص بك:

git init
git add .
git commit -m "Initial MkDocs project"

يقوم هذا بإعداد التحكم في الإصدارات. أضف site/ و venv/ إلى ملف .gitignore لاستبعاد نواتج البناء والبيئة الافتراضية:

site/
venv/

الرفع إلى GitHub: أنشئ مستودعاً جديداً على GitHub (على سبيل المثال، my-api-docs) وادفع مشروعك:

git remote add origin https://github.com/yourusername/my-api-docs.git
git branch -M main
git push -u origin main

استبدل yourusername باسم مستخدم GitHub الخاص بك. يقوم هذا بتحميل مشروع MkDocs الخاص بك إلى GitHub.

النشر على GitHub Pages: قم ببناء ونشر موقعك:

mkdocs gh-deploy

يقوم هذا الأمر ببناء موقعك، وارتكاب الملفات الثابتة إلى فرع gh-pages، ورفعها إلى GitHub. يستخدم MkDocs أداة ghp-import خلف الكواليس للتعامل مع هذا. سيكون موقعك متاحاً على العنوان https://yourusername.github.io/my-api-docs/ (امنحه بضع دقائق لينتشر).

قمت بتشغيل هذا لموقعي التجريبي، وكان متاحاً على GitHub Pages في أقل من دقيقة، ويمكن لأي شخص لديه الرابط الوصول إليه. إذا لم يعمل، تأكد من أن مستودع GitHub الخاص بك عام وتحقق من mkdocs gh-deploy --help للخيارات.

استكشاف بدائل MkDocs: توثيق APIdog

بينما يعتبر MkDocs رائعاً لتوثيق API الخفيف، قد ترغب في أداة تحتوي على المزيد من الميزات. هنا يأتي توثيق APIdog، وهو بديل قوي يبدو أجمل، وغني بالميزات، ويدعم الاستضافة الذاتية. يدمج APIdog تصميم API، والاختبار، والتوثيق في منصة واحدة، ويقدم ساحات لعب API تفاعلية، واختباراً آلياً، وميزات تعاونية - مثالي للفرق التي تحتاج إلى أكثر من مجرد مستندات ثابتة. إنه أكثر تعقيداً بقليل من MkDocs، ولكن إذا كنت تريد حلاً متكاملاً ومصقولاً، جرب APIdog!

إذا كنت تبدأ للتو في كتابة التوثيق أو تتطلع إلى رفع مستوى مهاراتك في التوثيق - خاصة عند العمل في فرق أو التعامل مع مشاريع معقدة - أوصي بشدة بتجربة Apidog. إنه يقدم مجموعة كبيرة من الميزات التي تبسط إدارة التوثيق للمشاريع المعقدة أو التعاونية. وأفضل جزء هو أنه يمكنك البدء مجاناً!

زر

نصائح لنجاح MkDocs

• تخصيص مظهرك: قم بتعديل مظهر Material في mkdocs.yml بخيارات مثل palette: { scheme: slate } للحصول على مظهر داكن.
• إضافة مكونات إضافية: قم بتثبيت مكونات إضافية مثل mkdocs-mkdocstrings لتكامل docstring في Python أو mkdocs-pdf-export-plugin لتصدير PDF.
• استخدام امتدادات Markdown: قم بتمكين الامتدادات في mkdocs.yml (على سبيل المثال، markdown_extensions: - toc: permalink: true) لجدول المحتويات أو الملاحظات.
• التحقق من السجلات: إذا فشل mkdocs serve أو gh-deploy، تحقق من مخرجات الطرفية أو mkdocs --help للحصول على دلائل.
• استكشاف المجتمع: انضم إلى مناقشات MkDocs على GitHub أو محادثة Gitter للحصول على نصائح وأفكار للمكونات الإضافية.

خلاصة: تبدأ مغامرة MkDocs الخاصة بك

تهانينا - لقد قمت بتثبيت واستخدام ونشر MkDocs لإنشاء توثيق API أنيق! من إعداد مشروع إلى النشر على GitHub Pages، لقد بنيت موقعاً احترافياً سهل الصيانة والمشاركة. حاول إضافة المزيد من نقاط النهاية، وتجربة المكونات الإضافية، أو تعديل المظهر لجعله خاصاً بك. إذا كنت تريد بديلاً غنياً بالميزات، تحقق من توثيق APIdog لتجربة من المستوى التالي! توثيق سعيد!