مستندسازی پروژه های Rust خود با mdBook

مستندات پروژه خوب یک دارایی حیاتی است و mdBook با خروجی تمیز و ساختاری منظم کمک خواهد کرد.

مستندسازی نقشی اساسی در موفقیت یک پروژه دارد. این یک چراغ دانش است که توسعه دهندگان و کاربران را از طریق پیچیدگی های پروژه راهنمایی می کند.

جامعه Rust اهمیت مستندات جامع در پروژه های نرم افزاری را می شناسد و Rust یک ابزار اسناد رسمی دارد: mdBook. این برنامه مستندات پروژه Rust را آسان می کند و شما را تشویق می کند تا از شیوه های مستندسازی موثر استفاده کنید.

mdBook چیست؟

mdBook یک ابزار مستندسازی رایگان است که برای پروژه های Rust طراحی شده است. از Markdown (یک زبان نشانه گذاری سبک) برای ایجاد مستندات پروژه جذاب و قابل پیمایش استفاده می کند.

یکی از اهداف اصلی مستندسازی، پر کردن شکاف بین کد و درک انسانی است. mdBook با ارائه یک قالب ساختاریافته که مرور و جستجوی اسناد را آسان می کند، برتری می یابد.

mdBook از همکاری با یک پلت فرم متمرکز اشتراک‌گذاری دانش برای سهامداران برای مشارکت در مستندسازی پشتیبانی می‌کند.

mdBook کار تیمی را ترویج می‌کند، تبادل ایده را تشویق می‌کند، و درک جمعی از پروژه را تضمین می‌کند و فرآیند اسناد به‌عنوان کد شما را بهبود می‌بخشد. این رویکرد مشارکتی بهره وری را افزایش می دهد، سیلوهای دانش را به حداقل می رساند و گردش کار توسعه را تقویت می کند.

شروع کار با mdBook

mdBook یک ابزار خط فرمان است که می توانید آن را از طریق منابع مختلف نصب کنید.

mdBook در رجیستری بسته Cargo موجود است. اگر Rust and Cargo را روی دستگاه خود نصب کرده اید، می توانید از دستور cargo install برای نصب ابزار خط فرمان استفاده کنید.

cargo install mdbook

همچنین می توانید mdBook را با Homebrew نصب کنید:

brew install mdbook

هنگامی که آن را نصب کردید، می توانید از دستور mdbook –version برای تأیید نصب استفاده کنید. دستور نسخه mdBook را که نصب کرده اید چاپ می کند.

با دستور init می توانید یک پروژه مستندات mdBook جدید را مقداردهی اولیه کنید.

mdbook init my-docs

این دستور مثال یک دایرکتوری جدید به نام my-docs با ساختار فایل لازم برای پروژه شما ایجاد می کند.

mdBook از یک ساختار ساده برای سازماندهی اسناد استفاده می کند:

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

در اینجا یک نمای کلی از ساختار فایل مستندات mdBook آمده است:

• book/: این فهرست حاوی خروجی نهایی مستندات شماست.
• book.toml: این فایل پیکربندی پروژه مستندسازی شماست. این به شما امکان می دهد تنظیمات و گزینه های مختلفی را تعریف کنید.
• src/: این دایرکتوری حاوی فایل های منبع برای مستندات شما است.
• SUMMARY.md: این فایل به عنوان فهرست مطالب برای مستندات شما عمل می کند. تمام فصل ها و بخش ها را فهرست می کند.

شما می توانید از دایرکتوری ها و تنظیمات اضافی برای نیازهای خاص پروژه خود استفاده کنید.

ایجاد و سازماندهی فصل ها و بخش ها

فایل SUMMARY.md را در ویرایشگر متن مورد علاقه خود باز کنید و این خطوط کد Markdown را اضافه کنید:

# Table of Contents

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

شما سه فصل به مستندات خود اضافه کرده‌اید: مقدمه، شروع، و استفاده پیشرفته.

یک دایرکتوری src/chapters ایجاد کنید و فایل های Markdown را برای هر فصل در داخل آن در زیر شاخه/فصل ایجاد کنید.

همانطور که فایل های Markdown معمولی را می نویسید، اسناد را در فایل های Markdown برای هر فصل می نویسید.

در اینجا توضیح کد نمونه برای فایل heads/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 serve برای ارائه اسناد خود استفاده کنید.

mdbook serve

هنگام اجرای دستور، mdBook اسناد پروژه شما را در پورت لوکال هاست 3000 ارائه می کند، بنابراین می توانید آن را در مرورگر http://localhost:3000/ مشاهده کنید.

در اینجا مروری بر سایر دستورات mdBook است که می توانید از آنها برای بهبود مستندات پروژه خود استفاده کنید:

فرمان

شرح

init

ساختار دیگ بخار و فایل های کتاب جدید را ایجاد می کند.

ساختن

یک کتاب از فایل های علامت گذاری شده آن می سازد.

تست

تست‌هایی که نمونه‌های کد Rust یک کتاب جمع‌آوری می‌کنند.

تمیز

یک کتاب ساخته شده را حذف می کند.

تکمیل

تکمیل پوسته برای پوسته خود را به stdout ایجاد کنید.

تماشا کردن

فایل های یک کتاب را تماشا می کند و آن را بر اساس تغییرات بازسازی می کند.

خدمت

کتابی را ارائه می کند و آن را بر اساس تغییرات بازسازی می کند.

کمک

این پیام یا کمک فرمان(های فرعی) داده شده را چاپ کنید.

mdBook می تواند گردش کار مستندات پروژه Rust شما را بهبود بخشد. اکثر پروژه‌های Rust از فایل‌های mdBook در سایر پلتفرم‌های مستندسازی استفاده می‌کنند.

برنامه های وب پیچیده را در Rust بسازید و آنها را با mdBook مستند کنید

Rust mdBook را با یک رندر سفارشی که فرمت های خروجی را تولید می کند، تقویت می کند. رندر می تواند به سرعت فرمت های خروجی را بدون مصرف منابع زیاد تولید کند.

می توانید از mdBook برای مستندسازی برنامه های وب مبتنی بر Rust خود استفاده کنید. با وارد کردن برنامه‌های وب Rust خود با mdBook، می‌توانید همکاری را از طریق یک فرآیند اسناد به‌عنوان کد صاف تقویت کنید.

سوالات متداول

س: از کدام ویرایشگر برای نوشتن Markdown استفاده کنم؟

مزیت بزرگ Markdown این است که متن ساده است، بنابراین می توانید تقریباً از هر ویرایشگر دلخواه خود مانند Notepad، Vim یا Sublime Text استفاده کنید. شما می توانید از یک IDE مانند VSCode استفاده کنید، و حتی یک کلمه پرداز کامل مانند Microsoft Word می تواند Markdown را مدیریت کند.

س: تفاوت بین mdBook و MkDocs چیست؟

مانند mdBook، MkDocs یک مولد سایت ایستا است که متخصص در مستندسازی است. اما، در حالی که mdBook پروژه های Rust را مدیریت می کند، MkDocs ابزاری برای توسعه دهندگان پایتون است.

س: آیا Rust دارای Docstrings است؟

Docstrings به شما امکان می دهد اسناد را با استفاده از نظرات برای حاشیه نویسی کد خود خودکار کنید. زبان‌هایی از جمله جاوا اسکریپت و پایتون از رشته‌های اسناد پشتیبانی می‌کنند و Rust نیز از آن پشتیبانی می‌کند.

منبع مقاله