Документирование проекта Rust с помощью mdBook

Сообщество Rust осознает важность всеобъемлющей документации для проектов разработки программного обеспечения, поэтому Rust предоставил официальную программу документирования под названием mdBook.

Что такое мдбук?

mdBook — это бесплатный инструмент документации для программирования проектов на Rust. Он использует Markdown для создания привлекательной и простой в навигации проектной документации.

Основная цель документации — преодолеть разрыв между кодом и человеческим пониманием. mdBook впечатляет тем, что предоставляет структурированный формат, облегчающий просмотр и поиск текста.

mdBook поддерживает совместную работу с централизованной платформой для обмена знаниями, чтобы заинтересованные стороны могли внести свой вклад в документацию.

mdBook способствует командной работе, поощряет обмен идеями и обеспечивает общее понимание проекта, улучшая процесс документирования в виде кода. Совместные методы повышают производительность, уменьшают объем знаний и улучшают рабочие процессы разработки.

Начать работу с mdBook

mdBook — это инструмент командной строки, который можно установить из разных источников.

mdBook доступен в пакете реестра Cargo. Если на вашем компьютере установлены Rust и Cargo, вы можете использовать команду cargo install для установки этого инструмента командной строки.

грузовая установка mdbook

Вы также можете установить mdBook с помощью Homebrew:

варить установить mdbook

После установки вы можете использовать команду mdbook –version для проверки установки. Эта команда выводит версию mdBook, которую вы установили.

Вы можете инициализировать проект документации mdBook с помощью команды init.

mdbook инициализирует мои документы

В этом примере команда создает новую папку с именем my-docs с необходимой файловой структурой для проекта.

mdBook использует простую структуру для организации документов:

. ├── book ├── book.toml └── источник ├── SUMMARY.md └── Chapter_1.md

Вот обзор файловой структуры документа mdBook:

book/ : этот каталог содержит окончательный вывод документа.
book.toml : это файл конфигурации для проекта документации. Это позволяет вам определять различные настройки и варианты.
src/ : этот каталог содержит исходный файл документа.
SUMMARY.md: этот файл действует как оглавление документа. В нем перечислены все записи и разделы.

Вы можете использовать дополнительные папки и конфигурации для конкретных нужд вашего проекта.

Создание и организация элементов и разделов

Откройте файл SUMMARY.md в текстовом редакторе и добавьте следующие строки в код Markdown:

# Содержание – (Введение)(chapters/introduction.md) – (Начало работы)(chapters/getting-started.md) – (Расширенное использование)(chapters/advanced-usage.md)

Вы добавили в документ 3 раздела, в том числе: Введение, Начало работы и Расширенное использование.

Создайте папку src/chapters и создайте файл Markdown для каждой главы внутри главы/раздела.

Вы будете документировать в файле Markdown каждую главу при написании обычного файла Markdown.

Объясните пример кода для файла Chapters/advanced-usage.md.

# Расширенное использование В этой главе будут рассмотрены некоторые расширенные сценарии использования наших программ на Rust. (//): # (Раздел с примерами) ## Параллельная обработка Одной из мощных возможностей Rust является возможность легко выполнять параллельную обработку. Вот пример фрагмента кода, который демонстрирует параллельную обработку с использованием контейнера `rayon`: (//): # (Ví dụ đoạn code Rust) “`rust use rayon::prelude::*; fn main() { let numbers = vec!(1, 2, 3, 4, 5); пусть суммирует: i32 = numbers.par_iter().sum(); println!(“Сумма: {}”, sum); } Tại đây, bạn đã nhập crate rayon và dùng par_iter để lặp cac số векторная песня. Bạn đã dùng phương thức sum để tính tổng số cac phần tử песня песня.

Раздел «Параллельная обработка» начинается с синтаксиса Markdown #, определяющего имя раздела.

Не забудьте следовать обычному синтаксису Markdown для форматирования контента. mdBook поддерживает большую часть функций Markdown, включая списки, абзацы, ссылки и многое другое.

После того, как вы написали документ, вы можете использовать команды mdBook для работы с ним. Например, вы можете использовать команду сервера mdbook для обработки документов.

mdbook служить

Когда вы запустите эту команду, mdBook обработает документ проекта на локальном порту 3000, чтобы вы могли просмотреть его в своем браузере по адресу