كيفية هيكلة توثيق NextPDF

لمحة سريعة

يلتزم دليل ⁨NextPDF⁩ بعقد ثابت. لكل صفحة موضوع واحد، ووضع ⁨Diataxis⁩ واحد، ونوع صفحة واحد. ولكل نوع صفحة مجموعة مطلوبة من عناوين المستوى الثاني. تحافظ مجموعة صغيرة من البيانات الوصفية والبوابات على اتساق البنية مع نمو الدليل.

تعرض هذه الصفحة هذا النظام بإيجاز حتى تضع مساهمتك في موضعها الصحيح. يوجد العقد المعياري الكامل، بما في ذلك قوائم العناوين الدقيقة، وقواعد الاستشهاد، وإجراء ربط البوابات، في مستند الحوكمة الداخلي docs/style/expansion-standard.md. اقرأ هذه الصفحة أولًا. وارجع إلى ذلك المستند عند التأليف.

اختيار نوع الصفحة

طبّق هذه القواعد بالترتيب لتقرر ما إذا كنت ستضيف صفحة جديدة أو توسّع صفحة قائمة:

1. إذا كان المحتوى موضوعًا مستقلًا لا يتوقع القارئ وجوده في الصفحة القائمة، فأضف صفحة جديدة.
2. إذا كان المحتوى يُكمّل موضوعًا تتناوله الصفحة القائمة بالفعل، فوسّع تلك الصفحة.
3. إذا كان المحتوى تفصيلًا متعمقًا من شأنه أن يضخّم صفحة تثبيت أو بداية سريعة أو مهمة، فانقله إلى صفحة منفصلة واربط إليها.
4. وإلا، فوسّع الصفحة القائمة.

بعد أن تتأكد من ضرورة وجود الصفحة، حدّد وضع ⁨Diataxis⁩ الخاص بها. فهذا الوضع يحدّد نوع الصفحة:

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

اللغة الواضحة هي الأساس لكل وضع، وليست وضعًا منفصلًا.

كتالوج أنواع الصفحات

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

• أنواع الفهرس: section-index، api-index، extension-index.
• نوع المرجع: api-reference. أعد استخدام هذا النوع لأي صفحة تحتوي على جدول واجهة برمجة التطبيقات القياسي، بما في ذلك مراجع الخادم وحزمة تطوير ⁨Python.⁩
• نوع الشرح: developer-guide. أعد استخدام هذا النوع لنصوص البنية ودورة الحياة ونقاط التوسعة، بما في ذلك أدلة الخادم وحزمة تطوير ⁨Python.⁩
• الأنواع الجديدة القائمة على التسمية فقط: premium-feature-guide وtask-guide، وكلاهما للصفحات التي لا تحتوي على جدول واجهة برمجة تطبيقات.

تبدأ كل صفحة بـ ## At a glance. وتتضمّن كل صفحة api-reference جدول واجهة برمجة التطبيقات المشترك وعنوان Development notes. العناوين المطلوبة كلها من المستوى الثاني، ويقع كل عنوان منها في سطر مستقل. يمكنك إضافة عناوين أخرى أسفلها.

قائمة تحقق التأليف

عندما تكتب صفحة، استوفِ كلتا قائمتي التحقق. يبيّن المعيار الداخلي كل بند بصيغة معيارية ويربطه بالمعيار الداعم له.

سهولة الاستخدام للمطوّرين:

• استمد الأمثلة القابلة للتشغيل من examples/ أو tests/Cookbook، وضع لكل كتلة مسيّجة سلسلة معلومات title=.
• بيّن المتطلبات المسبقة في البيانات الأمامية وفي المقدمة.
• أظهر الخرج المتوقع لأي نموذج يُنتج خرجًا.
• أبقِ الكتل جاهزة للنسخ واللصق: لغة واحدة لكل كتلة، وأسماء كاملة عند أول استخدام، ومن دون أحرف موجِّه أوامر زائدة في النهاية.
• أظهر شفرة آمنة افتراضيًا: تستخدم نماذج الإنتاج try/catch مع أكثر استثناءات ⁨NextPDF⁩ تحديدًا ولا تستخدم أبدًا كتلة ⁨catch⁩ فارغة.
• اختم بروابط للمتابعة واضبط related: في البيانات الأمامية.

الجاهزية للترجمة:

• اكتب فكرة واحدة في كل جملة حتى تبقى الترجمة الآلية محدودة النطاق.
• أبقِ العناوين والتسميات قصيرة لأن معظم اللغات الهدف تتوسّع.
• تجنّب التعبيرات الاصطلاحية.
• أبقِ أسماء الرموز، ومفاتيح الإعدادات، وأعلام سطر الأوامر، وأسماء الاستثناءات بتنسيق الشفرة؛ ولا تُترجم أبدًا أسماء المعايير مثل PDF/A-4 وPAdES وeIDAS.
• اضبط i18n_ready وxliff_segments بصدق، واكتب بترميز ⁨Unicode NFC.⁩

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

ربط البوابات

اربط صفحة جديدة باتباع هذا الإجراء المرتّب:

1. جهّز بنية الصفحة بحيث تطابق بياناتها الأمامية مخطط الموقع.
2. ألّف المتن وفقًا للعناوين المطلوبة لنوع الصفحة.
3. أضف مدخل { path, owner, kind, headings[] } إلى docs/manual-contract.json. يكون المسار نسبيًا إلى src/content/docs، ويستخدم الشرطات المائلة الأمامية، ولا يحمل شرطة مائلة في البداية ولا ...
4. في حالة مرجع واجهة برمجة التطبيقات، أضف رموز الصفحة إلى docs/api-coverage-manifest.json؛ ويجب أن يظهر كل رمز في الصفحة وأن يكون موجودًا في المصدر.
5. لا تحدّث docs/source-manifest.json إلا عندما تأتي الصفحة من مستودع مصدر جديد.
6. أضف الصفحة إلى مجموعة الشريط الجانبي الصحيحة في astro.config.mjs كمدخل صريح.
7. أضف صفًّا لتغطية اللغات مع ضبط جميع خلايا اللغات السبع عشرة على missing لصفحة بالإنجليزية فقط.
8. شغّل بوابات التوثيق، وعملية البناء، وميزانية الأداء.

توجد الصفحات المملوكة للموقع ضمن src/content/docs، وتضبط owner على nextpdf-docs، ولا تحمل أبدًا علامة تجميع. تأتي الصفحات المجمَّعة من مستودع مصدر. يوجد علم النشر الخاص بها في البيانات الأمامية للمصدر، لذا حرّرها هناك، لا هنا.

انظر أيضًا

• عمليات التكامل: أكبر مثال مطبَّق على بنية الدليل عبر حزم متعددة.
• يحتوي مستند الحوكمة الداخلي docs/style/expansion-standard.md على العقد الكامل: قوائم العناوين الدقيقة لكل نوع صفحة، وقواعد الاستشهاد، وإجراء ربط البوابات الكامل.