ما هو Doxygen وكيفية تنزيله واستخدامه؟

هل سئمت من كتابة التوثيق لمشاريعك يدويًا؟ تعرف على doxygen، الأداة مفتوحة المصدر التي تنشئ توثيقًا رائعًا تلقائيًا من تعليقات الكود الخاصة بك في لمح البصر. لقد قمت بتشغيلها في 15 دقيقة، وجعلت توثيق مشروع C++ الخاص بي يبدو احترافيًا! في هذا الدليل، سأشرح ما هو doxygen، وأريك كيفية تنزيله وتثبيته، وسأرشدك خلال إنشاء أول توثيق لك. سواء كنت مطورًا أو طالبًا، دعنا نجعل كودك يتألق مع doxygen!

ما هو Doxygen؟ بطل توثيق الكود الخاص بك

Doxygen هي أداة مجانية ومفتوحة المصدر تنشئ توثيقًا من الكود المصدري المشروح. تقوم بمسح تعليقات الكود الخاص بك (بلغات مثل C++، C، Python، Java، والمزيد) وتنشئ مستندات HTML أو PDF أو LaTeX مع رسوم بيانية وإحالات مرجعية وفهارس. إليك لماذا doxygen ضروري:

• دعم متعدد اللغات: يعمل مع C++، C، Python، Java، PHP، وغيرها.
• مخرجات غنية: ينتج HTML، PDF، صفحات دليل (man pages)، أو حتى LaTeX للطباعة.
• مرئيات: ينشئ تلقائيًا رسوم بيانية للمكالمات (call graphs) ورسوم بيانية للفئات (class diagrams) (باستخدام Graphviz).
• قابل للتخصيص: يمكنك تعديل القوالب للحصول على مستندات احترافية ذات علامة تجارية.
• مفتوح المصدر: موثوق به من قبل المطورين، مع أكثر من 1.8 ألف نجمة على GitHub.

يصف المستخدمون doxygen بأنه “منقذ” للحفاظ على توثيق المشاريع مرتبًا. هل أنت مستعد لتجربته؟ لنبدأ!

لماذا تستخدم Doxygen؟

Doxygen يوفر الوقت ويحافظ على توثيق الكود الخاص بك منظمًا. تشمل الفوائد:

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

لقد استخدمت doxygen لمشروع Python، وأعجب فريقي بالوثائق التفاعلية بصيغة HTML!

كيفية تنزيل وتثبيت Doxygen: دليل خطوة بخطوة

دعنا نبدأ بتشغيل doxygen. سأغطي أنظمة Windows و macOS و Linux، بناءً على تجربتي على جهاز الكمبيوتر المحمول بنظام Windows. تابع معي!

1. تنزيل Doxygen

• قم بزيارة الموقع الرسمي لـ doxygen: doxygen.nl/download.html.
• اختر نظام التشغيل الخاص بك:
• Windows: احصل على ملف التثبيت .exe (مثل doxygen-1.12.0.windows.x64.bin.zip).
• macOS: قم بتنزيل ملف .dmg أو استخدم Homebrew (موصى به).
• Linux: استخدم مدير الحزم الخاص بك أو قم بتنزيل الملف الثنائي.
• بالنسبة لنظام Windows، قمت بتنزيل مُثبّت النظام 64 بت (حوالي 55.1 ميجابايت، استغرق بضع ثوانٍ).

اختياري: تثبيت Graphviz للرسوم البيانية

• يستخدم Doxygen أداة Graphviz لإنشاء رسوم بيانية للمكالمات ورسوم بيانية للفئات.
• قم بالتنزيل من graphviz.org/download أو قم بالتثبيت عبر:
• Windows: مُثبّت .exe.
• macOS: brew install graphviz.
• Linux: sudo apt-get install graphviz (Ubuntu/Debian) أو ما يعادله.
• لقد قمت بتثبيت Graphviz للحصول على مستندات أكثر تفصيلاً—الأمر يستحق ذلك!

2. تثبيت Doxygen

Windows:

أولاً. الإعداد باستخدام ملف Zip x64:

• فك ضغط الملف الذي تم تنزيله.
• قم بتشغيل doxygen.exe (لا يحتاج إلى إعداد) أو أضفه إلى متغير PATH الخاص بك:
• انسخ doxygen.exe إلى C:\Program Files\Doxygen.
• أضف C:\Program Files\Doxygen إلى متغيرات بيئة النظام > المسار (Path).

ثانياً. الإعداد باستخدام مُثبّت النظام x64:

• قم بتشغيل ملف setup.exe الذي قمت بتنزيله واتبع خطوات التثبيت البسيطة.

للتحقق، افتح موجه الأوامر واكتب: doxygen --version.

macOS (باستخدام Homebrew):

brew install doxygen

تحقق: doxygen --version.

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install doxygen

تحقق: doxygen --version.

3. إنشاء مشروع نموذجي

دعنا نختبر doxygen باستخدام مشروع C++ بسيط (يعمل أيضًا مع Python، Java، إلخ).

• أنشئ مجلدًا: mkdir my-doxy-project && cd my-doxy-project.
• أضف ملفًا باسم main.cpp:

/**
 * @file main.cpp
 * @brief A sample program to demonstrate Doxygen.
 * @author Your Name
 */

#include <iostream>

/**
 * @brief Prints a greeting message.
 * @param name The name to greet.
 * @return void
 */
void sayHello(const std::string& name) {
    std::cout << "Hello, " << name << "!" << std::endl;
}

/**
 * @brief Main function.
 * @return 0 on success.
 */
int main() {
    sayHello("Doxygen User");
    return 0;
}

• هذه التعليقات /** */ متوافقة مع doxygen وتحتوي على وسوم مثل @brief، @param.

4. إنشاء ملف إعداد Doxygen

• في مجلد مشروعك، قم بتشغيل:

doxygen -g Doxyfile

• هذا ينشئ ملف Doxyfile بإعدادات افتراضية (حوالي 800 سطر!).
• قم بتحرير ملف Doxyfile (استخدم أي محرر نصوص) لتعديل:
• عيّن PROJECT_NAME = "My Doxy Project".
• عيّن OUTPUT_DIRECTORY = docs (ينشئ مجلدًا باسم docs).
• مكّن الرسوم البيانية (إذا كان Graphviz مثبتًا): HAVE_DOT = YES، CALL_GRAPH = YES.
• قمت بتعيين OUTPUT_DIRECTORY للحفاظ على مستنداتي مرتبة.

5. تشغيل Doxygen

• لإنشاء التوثيق:

doxygen Doxyfile

• يقوم Doxygen بمسح ملف main.cpp، مما ينشئ مجلدًا باسم docs يحتوي على المخرجات بصيغة HTML. افتح ملف docs/html/index.html في متصفحك. سترى صفحة رئيسية أنيقة تحتوي على اسم مشروعك، وقائمة بالملفات، وتوثيق دالة sayHello. لقد انبهرت بالرسم البياني للمكالمات!

6. استكشاف وتخصيص المخرجات

• مستندات HTML: قوائم قابلة للنقر، تفاصيل الدوال، ورسوم بيانية (إذا كان Graphviz قيد التشغيل).
• مخرجات PDF: في ملف Doxyfile، عيّن GENERATE_LATEX = YES، ثم قم بتشغيل:

cd docs/latex
make

هذا ينشئ ملف refman.pdf. يمكنك فتح مجلد latex في محرر قوالب latex وعرض النتائج! لقد جربت ذلك باستخدام محرر LaTex عبر الإنترنت Overleaf ببساطة عن طريق سحب وإسقاط بعض الملفات وتشغيل المشروع لعرض المخرجات. سهل جدًا!

• تخصيص: قم بتحرير ملف Doxyfile للشعارات، السمات، أو الفلاتر (مثل HTML_HEADER لـ CSS مخصص).
• يمكنك إضافة شعار إلى مستندات HTML الخاصة بك لجعلها تبدو احترافية للغاية!

استكشاف أخطاء Doxygen وإصلاحها

• لا يوجد مخرجات؟ تحقق من INPUT في ملف Doxyfile (يجب أن يتضمن مجلد الكود الخاص بك) وقم بتشغيل doxygen Doxyfile مرة أخرى.
• رسوم Graphviz البيانية مفقودة؟ تأكد من تثبيت Graphviz وأن HAVE_DOT = YES في ملف Doxyfile.
• الأمر غير موجود؟ أضف doxygen إلى متغير PATH الخاص بك أو أعد التثبيت.
• تحتاج مساعدة؟ تحقق من doxygen.nl/manual أو Stack Overflow.

تخصيص وتوسيع Doxygen

ارتقِ بمستوى استخدامك لـ doxygen:

• وسوم مخصصة: استخدم @note، @warning، أو أسماء مستعارة مخصصة في التعليقات.
• دعم Markdown: اكتب التعليقات بصيغة Markdown لتنسيق أغنى.
• فلاتر: وثّق اللغات غير المدعومة (مثل نصوص shell البرمجية) باستخدام فلاتر مخصصة.
• تكامل CI: أضف doxygen إلى GitHub Actions لإنشاء التوثيق تلقائيًا.

لقد أضفت تعليقات Markdown إلى مشروع Python الخاص بي—كان التوثيق نظيفًا جدًا!

أفكار ختامية: لماذا Doxygen ضروري للتوثيق

Doxygen هو أداة قوية لتوثيق الكود، حيث يقوم بأتمتة المهام المملة بأناقة. دعمها متعدد اللغات ومخرجاتها الغنية تتفوق على كتابة التوثيق اليدوي في أي وقت. بالتأكيد، قد يبدو ملف Doxyfile معقدًا، لكن دليل Doxygen هو منقذ. بالمقارنة مع أدوات مثل Sphinx، يتفوق doxygen في مشاريع C/C++ بفضل الرسوم البيانية المرئية.

هل أنت مستعد للتوثيق مثل المحترفين؟ قم بتثبيت doxygen، أنشئ التوثيق، وشارك إعداداتك—أنا متحمس لرؤية نتائجك!