توثيق مشاريع الصدأ الخاصة بك مع mdBook

يلعب التوثيق دورًا محوريًا في نجاح المشروع. إنها منارة المعرفة التي توجه المطورين والمستخدمين خلال تعقيدات المشروع.

يدرك مجتمع Rust أهمية التوثيق الشامل في مشاريع البرامج ، ولدى Rust أداة توثيق رسمية: mdBook. يسهل هذا البرنامج توثيق مشروع Rust ويشجعك على تبني ممارسات التوثيق الفعالة.

ما هو mdBook؟

mdBook هو ملف أداة توثيق مجانية مصممة لمشاريع الصدأ. يستخدم Markdown (لغة ترميز خفيفة الوزن) لإنشاء وثائق مشروع جذابة وقابلة للملاحة.

أحد الأهداف الأساسية للتوثيق هو سد الفجوة بين الكود والفهم البشري. يتفوق mdBook من خلال تقديم تنسيق منظم يجعل من السهل استعراض المستندات والبحث فيها.

يدعم mdBook التعاون مع منصة مركزية لمشاركة المعرفة لأصحاب المصلحة للمساهمة في التوثيق.

يشجع mdBook العمل الجماعي ، ويشجع على تبادل الأفكار ، ويضمن فهمًا جماعيًا للمشروع ، مما يؤدي إلى تحسين عملية المستندات كرمز. يعزز هذا النهج التعاوني الإنتاجية ويقلل من صوامع المعرفة ويقوي سير عمل التطوير.

الشروع في العمل مع mdBook

mdBook هي أداة سطر أوامر يمكنك تثبيتها من خلال مصادر مختلفة.

يتوفر mdBook في سجل حزم Cargo. إذا كان لديك Rust and Cargo مثبتًا على جهازك ، فيمكنك استخدام ملف تثبيت البضائع الأمر لتثبيت أداة سطر الأوامر.

cargo install mdbook

يمكنك أيضًا تثبيت mdBook مع Homebrew:

brew install mdbook

بمجرد تثبيته ، يمكنك استخدام mdbook - الإصدار أمر للتحقق من التثبيت. يقوم الأمر بطباعة إصدار mdBook الذي قمت بتثبيته.

يمكنك تهيئة مشروع توثيق mdBook جديد باستخدام الأمر init.

mdbook init my-docs

ينشئ هذا الأمر المثال دليلاً جديدًا باسم مستنداتي مع بنية الملف اللازمة لمشروعك.

يستخدم mdBook بنية بسيطة لتنظيم الوثائق:

.
├── book
├── book.toml
└── src
 ├── SUMMARY.md
 └── chapter_1.md

فيما يلي نظرة عامة على بنية ملف وثائق mdBook:

• كتاب/: يحتوي هذا الدليل على الإخراج النهائي لوثائقك.
• book.toml: هذا هو ملف التكوين لمشروع التوثيق الخاص بك. يسمح لك بتحديد الإعدادات والخيارات المختلفة.
• src /: يحتوي هذا الدليل على ملفات المصدر لوثائقك.
• الملخص. md: هذا الملف بمثابة جدول محتويات لوثائقك. يسرد جميع الفصول والأقسام.

يمكنك استخدام أدلة إضافية وتكوين لاحتياجات مشروعك المحددة.

إنشاء وتنظيم الفصول والأقسام

افتح ال الملخص. md ملف في محرر النصوص المفضل لديك وإضافة هذه السطور من Markdown code:

# Table of Contents
- [Introduction](chapters/introduction.md)
- [Getting Started](chapters/getting-started.md)
- [Advanced Usage](chapters/advanced-usage.md)

لقد أضفت ثلاثة فصول إلى وثائقك: المقدمة ، والبدء ، والاستخدام المتقدم.

إنشاء src / الفصول الدليل وإنشاء ملفات Markdown لكل فصل بداخله ضمن ملف فصول / الدليل.

ستكتب الوثائق في ملفات Markdown لكل فصل وأنت تكتب بشكل منتظم ملفات Markdown.

إليك مثال على شرح رمز لـ الفصول / Advanced-usage.md ملف.

# Advanced Usage
This chapter will explore some advanced usage scenarios for our Rust
programs.
[//]: # (An Example Section)
## Parallel Processing
One of Rust's powerful features of Rust is its ability to perform parallel
processing easily. Here's an example code snippet that demonstrates parallel
processing using the `rayon` crate:
[//]: # (Rust code snippet example)
```rust
use rayon:: prelude::*;
fn main() {
 let numbers = vec![1, 2, 3, 4, 5];
 let sum: i32 = numbers.par_iter().sum();
 println!("The sum is: {}", sum);
}
Here, you imported the rayon crate and used its par_iter method to iterate
over the numbers vector in parallel. 
You used the sum method to calculate the sum of all the elements in
parallel.

يبدأ قسم المعالجة المتوازية بامتداد # صيغة Markdown تحدد اسم القسم.

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

بعد كتابة وثائقك ، يمكنك استخدام أوامر mdBook المتنوعة للعمل عليها. على سبيل المثال ، يمكنك استخدام ملف يخدم mdbook الأمر لخدمة وثائقك.

mdbook serve

عند تشغيل الأمر ، سيخدم mdBook وثائق مشروعك على المضيف المحلي المنفذ 3000 ، لذا يمكنك مشاهدته في متصفح على http://localhost: 3000/.

فيما يلي نظرة عامة على أوامر mdBook الأخرى التي يمكنك استخدامها لتحسين وثائق مشروعك:

يمكن لـ mdBook تحسين سير عمل وثائق مشروع Rust. تستخدم معظم مشاريع Rust الملفات من mdBook على منصات التوثيق الأخرى.

أنشئ تطبيقات ويب متطورة في حالة الصدأ ووثقها باستخدام mdBook

يقوم Rust بتشغيل mdBook باستخدام جهاز عرض مخصص يقوم بإنشاء تنسيقات الإخراج. يستطيع العارض إنشاء تنسيقات الإخراج بكفاءة بسرعة دون استهلاك العديد من الموارد.

يمكنك استخدام mdBook لتوثيق تطبيقات الويب القائمة على Rust. عن طريق إدخال تطبيقات الويب Rust الخاصة بك مع mdBook ، يمكنك تعزيز التعاون من خلال عملية المستندات كرمز سلس.