Biên soạn tài liệu cho dự án Rust bằng mdBook

Tài liệu đóng vai trò quan trọng trong thành công của một dự án. Nó là hướng dẫn cho lập trình viên và người dùng hiểu rõ dự án hơn.

Cộng đồng Rust nhận ra tầm quan trọng của tài liệu toàn diện cho các dự án phát triển phần mềm nên Rust đã cung cấp một công cụ soạn tài liệu chính thức, mang tên: mdBook.

mdBook là gì?

mdBook là một công cụ soạn tài liệu miễn phí dành cho các dự án lập trình bằng Rust. Nó dùng Markdown để tạo tài liệu dự án hấp dẫn và dễ điều hướng.

Một mục tiêu chính của tài liệu là thu hẹp khoảng cách giữa code và sự hiểu biết của con người. mdBook gây ấn tượng bằng cách cung cấp một định dạng có cấu trúc để làm văn bản dễ duyệt và tìm kiếm.

mdBook hỗ trợ cộng tác với một nền tảng tập trung chia sẻ kiến thức cho các bên liên quan để đóng góp vào tài liệu.

mdBook thúc đẩy tinh thần đồng đội, khuyến khích trao đổi ý tưởng và đảm bảo hiểu biết chung về dự án, cải thiện quá trình biên soạn tài liệu dưới dạng code. Phương thức cộng tác nâng cao năng suất, giảm thiểu khối lượng kiến thức và tăng cường quy trình phát triển.

Bắt đầu với mdBook

mdBook là một công cụ dòng lệnh mà bạn có thể cài đặt qua các nguồn khác nhau.

mdBook có sẵn trên registry package của Cargo. Nếu đã cài Rust và Cargo trên máy tính, bạn có thể dùng lệnh cargo install để cài đặt công cụ dòng lệnh này.

cargo install mdbook

Bạn cũng có thể cài đặt mdBook bằng Homebrew:

brew install mdbook

Sau khi đã cài đặt nó, bạn có thể dùng lệnh mdbook --version để xác minh cài đặt. Lệnh này in phiên bản của mdBook bạn đã cài.

Bạn có thể khởi tạo một dự án tài liệu mdBook bằng lệnh init.

mdbook init my-docs

Lệnh ví dụ này tạo một thư mục mới tên my-docs với cấu trúc file cần thiết cho dự án.

mdBook dùng cấu trúc đơn giản để sắp xếp tài liệu:

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

Dưới đây là tổng quan về cấu trúc file tài liệu của mdBook:

• book/: Thư mục này chứa đầu ra cuối cùng của tài liệu.
• book.toml: Đây là file cấu hình dành cho dự án tài liệu. Nó cho phép bạn xác định các cài đặt và lựa chọn khác nhau.
• src/: Thư mục này chứa file nguồn cho tài liệu.
• SUMMARY.md: File này hoạt động như bảng nội dung cho tài liệu. Nó liệt kê tất cả các mục và phần.

Bạn có thể dùng các thư mục bổ sung và cấu hình cho nhu cầu cụ thể của dự án.

Tạo và sắp xếp các mục và phần

Mở file SUMMARY.md trong trình chỉnh sửa văn bản và thêm những dòng này vào code Markdown:

# Table of Contents

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

Bạn đã thêm 3 phần vào tài liệu, bao gồm: Introduction, Getting Started và Advanced Usage.

Tạo thư mục src/chapters và và tạo file Markdown cho từng chương bên trong mục chapters/.

Bạn sẽ viết tài liệu trong file Markdown cho từng chương khi viết file Markdown thông thường.

Giải thích code mẫu cho file chapters/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:

[//]: # (Ví dụ đoạn code Rust)
```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);
}

Tại đây, bạn đã nhập crate rayon và dùng par_iter để lặp các số vector song song. 

Bạn đã dùng phương thức sum để tính tổng số các phần tử song song.

Phần Parallel Processing bắt đầu với cú pháp Markdown # xác định tên phần.

Nhớ tuân thủ cú pháp Markdown theo quy ước để định dạng nội dung. mdBook hỗ trợ hầu hết chức năng Markdown, bao gồm danh sách, đoạn văn, link…

Sau khi viết tài liệu, bạn có thể dùng các lệnh mdBook để thao tác trên tài liệu đó. Ví dụ, bạn có thể dùng lệnh mdbook server để xử lý tài liệu.

mdbook serve

Khi chạy lệnh này, mdBook sẽ xử lý tài liệu của dự án trên cổng localhost 3000, vì thế, bạn có thể xem nó trong trình duyệt tại http://localhost:3000/.

mdBook có thể cải thiện quy trình soạn tài liệu cho dự án Rust. Hãy thử và tự mình cảm nhận nhé!