DocFX là công cụ mạnh mẽ để tạo tài liệu API và tài liệu website tĩnh từ Markdown. Để tăng hiệu quả, việc sử dụng script batch giúp tự động hóa quá trình build và quản lý tài liệu trở nên dễ dàng hơn.
Nếu hiển thị phiên bản, DocFX đã được cài đặt thành công.
2. Khởi tạo dự án DocFX
Tạo cấu trúc dự án DocFX
Trong thư mục dự án, chạy lệnh:
docfx init
cmd.exe
PS D:\nqdev-wps\quyit\quyit-platform> docfx init --help
USAGE:
docfx init [OPTIONS]
OPTIONS:
-h, --help Prints help information
-y, --yes Yes to all questions
-o, --output Specify the output directory of the generated files
Lệnh này tạo ra file docfx.json và các thư mục cần thiết:
api/
articles/
toc.yml
Tùy chỉnh file docfx.json
Cập nhật file docfx.json để chỉ định nguồn tài liệu và output:
3. Sử dụng file batch tự động hóa
Nội dung file batch docfx-build.bat
File batch tự động hóa quá trình build DocFX, serve tài liệu, và tích hợp Git. Dưới đây là nội dung chính:
Biến cấu hình:
PROJECT_DIR: Thư mục hiện tại.
CONFIG_PATH: Đường dẫn file docfx.json.
OUTPUT_DIR: Thư mục chứa tài liệu sau khi build.
Lệnh chính:
--build: Build tài liệu.
--serve: Khởi chạy tài liệu trên trình duyệt.
--git: Commit và push tài liệu lên Git.
Nội dung tệp mẫu:
Ví dụ sử dụng:
cmd.exe
PS D:\nqdev-wps\quyit\quyit-platform> .\docfx-build.bat --help
Chuyen den nhan thu 1: --help
-----------------------------------------------------------
File script: docfx-build.bat
Ngay tao: 11/12/2024
Tac gia: [Nguyen Quy](quynh@vihatgroup.com)
-----------------------------------------------------------
Huong dan su dung script batch:
1. Build tai lieu DocFX:
docfx-build.bat --build
2. Build va xuat tai lieu ra file pdf:
docfx-build.bat --build --pdf
3. Build tai lieu va commit push (Git nhanh main/ develop):
docfx-build.bat --build --git
4. Build va serve tai lieu (mo trinh duyet):
docfx-build.bat --build --serve
5. Build va zip tai lieu:
docfx-build.bat --build --deploy
6. Zip tai lieu de trien khai:
docfx-build.bat --deploy
7. Serve tai lieu (mo trinh duyet):
docfx-build.bat --serve
8. Hien thi huong dan su dung:
docfx-build.bat --help
-----------------------------------------------------------
Press any key to continue . . .
4. Cách sử dụng script
Build tài liệu: Chạy lệnh:
docfx-build.bat --build
Tài liệu sẽ được xuất ra thư mục artifacts/docfx.
Serve tài liệu trên trình duyệt: Chạy lệnh:
docfx-build.bat --serve
Hỗ trợ Git: Nếu file batch có tích hợp Git, bạn có thể sử dụng:
docfx-build.bat --build --git
Xem hướng dẫn:
docfx-build.bat --help
5. Lợi ích khi sử dụng script
Tự động hóa: Giảm thao tác thủ công.
Tích hợp Git: Đảm bảo tài liệu luôn được cập nhật trên repository.
Dễ dàng mở rộng: Thêm các chức năng khác như kiểm tra lỗi, nén tài liệu, v.v.
Kết luận
Sử dụng DocFX cùng script batch là cách tuyệt vời để quản lý tài liệu cho các dự án .NET. Hy vọng bài viết đã cung cấp cho bạn kiến thức cần thiết để triển khai DocFX hiệu quả trong dự án của mình.
Hãy thử ngay và chia sẻ trải nghiệm của bạn!
Nếu bạn có thắc mắc hoặc cần thêm hỗ trợ, đừng ngần ngại để lại bình luận. 😊