تضمين الرموز
قم بتضمين الكود المباشر في وثائقك بالاسم، وليس برقم السطر. عدّل المصدر، وتحدث وثائقك تلقائياً.
# تضمين دالة بالاسم
![[auth.py#validate_token]]يستخرج Ohai دالة validate_token من auth.py ويعرضها مباشرة مع تمييز الصيغة. عندما تتغير الدالة، تحدث وثائقك تلقائياً.
لماذا هذا مهم
الوثائق التقليدية تتقادم. تقوم بنسخ الكود ولصقه في markdown، ثم يتطور الكود، وفجأة تجد أن وثائقك تكذب عليك. تضمين الرموز يحل هذه المشكلة من خلال معاملة ملفاتك المصدرية كمصدر وحيد للحقيقة.
على عكس مراجع أرقام الأسطر التي تنكسر مع كل إعادة هيكلة، يستخدم تضمين الرموز تحليل AST للعثور على الكود باسمه الفعلي—الدوال، الفئات، الهياكل، الثوابت. أعد تسمية ملف، أعد تنظيم الكود، أضف وظائف جديدة—طالما اسم الرمز موجود، تبقى وثائقك دقيقة.
حالات الاستخدام
توثيق API
أشر إلى توقيعات دوالك الفعلية، وليس التقريبات المكتوبة يدوياً التي تنحرف عن المزامنة.
سجلات قرارات البنية المعمارية
قم بتضمين الكود الذي تناقشه في ADRs. الأمثلة تبقى حديثة مع تطور قاعدة الكود.
أدلة الإعداد
أظهر للمطورين الجدد كيف تعمل المصادقة بكود مباشر يمكنهم الوثوق بأنه يطابق المستودع.
مراجعات الكود
اسحب دوال محددة إلى ملخص markdown للمراجعة والنقاش غير المتزامن.
دروس تعليمية
اشرح التطبيقات الحقيقية خطوة بخطوة. يمكن للقراء الوثوق بأن أمثلة الكود دائماً محدثة.
كتيبات التشغيل
قم بتضمين الإعدادات أو السكربت الدقيق الذي يحتاج فريق العمليات للرجوع إليه أثناء الحوادث.
اللغات المدعومة
أكثر من 30 لغة عبر تحليل AST بـ Tree-sitter. حتى مفاتيح JSON، ومسارات YAML، وجداول TOML.
هل أنت مستعد لتجربة وثائق لا تصبح قديمة أبداً؟
تحميل لنظام Mac