Sphinx là công cụ tạo tài liệu mạnh mẽ viết bằng Python, được thiết kế để chuyển đổi các văn bản thuần túy có đánh dấu thành nhiều định dạng đầu ra phong phú như HTML, PDF, hay EPUB. Mặc dù khởi nguồn là để phục vụ tài liệu cho chính Python, Sphinx hiện nay đã trở thành tiêu chuẩn cho nhiều loại tài liệu kỹ thuật, bao gồm mô tả API, handbook và tài liệu hướng dẫn người dùng.
Những ưu điểm nổi bật của Sphinx có thể kể đến như:
- Hỗ trợ đa dạng các ngôn ngữ đánh dấu, điển hình là reStructuredText và Markdown.
- Khả năng xuất ra nhiều định dạng tài liệu khác nhau.
- Hệ thống theme và giao diện có thể tùy biến sâu thông qua CSS và template.
- Tích hợp sẵn các extension giúp tự động hóa việc tạo tài liệu từ mã nguồn (API docs) và các đoạn mã mẫu.
- Tự động xây dựng bảng mục lục, chỉ mục và các tham chiếu chéo thông minh.
Quy trình làm việc với Sphinx thường bao gồm các bước cơ bản sau:
1. Cài đặt công cụ
Đầu tiên, bạn cần cài đặt gói Sphinx thông qua trình quản lý gói pip:
pip install sphinx
2. Khởi tạo cấu trúc dự án
Tạo một thư mục riêng biệt để chứa tài liệu (ví dụ: `docs`), sau đó chạy lệnh khởi tạo:
mkdir docs && cd docs
sphinx-quickstart
Lệnh này sẽ yêu cầu bạn nhập các thông số cấu hình. Bạn nên chọn tách biệt thư mục nguồn (`source`) và thư mục biên dịch (`build`) để quản lý dễ dàng hơn.
Welcome to the Sphinx 4.5.0 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
> Separate source and build directories (y/n) [n]: y
> Project name: My Awesome Project
> Author name(s): Tech Team
> Project release []: 1.0.2
> Project language [en]: en
Sau khi chạy xong, trong thư mục `docs` sẽ xuất hiện thư mục `source` (chứa file cấu hình `conf.py` và file chính `index.rst`) và file `Makefile` hỗ trợ lệnh build.
3. Soạn thảo nội dung
Bạn sử dụng reStructuredText hoặc Markdown để viết nội dung trong thư mục `source`. File `index.rst` đóng vai trò là trang chủ (trang bìa) của tài liệu.
4. Biên dịch tài liệu
Để xuất tài liệu sang định dạng HTML, hãy sử dụng lệnh:
make html
Kết quả sẽ được lưu trữ trong thư mục `build/html`.
Tự động tạo tài liệu từ mã nguồn (API Docs)
Sphinx cung cấp công cụ `sphinx-apidoc` giúp quét mã nguồn Python và tạo ra các file tài liệu tương ứng.
Bước 1: Cấu hình hệ thống
Mở file `docs/source/conf.py`, chỉnh sửa đường dẫn để Sphinx tìm thấy các module của dự án và kích hoạt các tiện ích mở rộng:
import sys
import os
sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
]
Bước 2: Sinh tài liệu từ module
Thực thi lệnh sau tại thư mục `docs`:
cd docs
sphinx-apidoc -o source ../my_project_module
Lệnh này sẽ sinh ra file `modules.rst` và các file `.rst` tương ứng với từng gói con. Hãy thêm `modules` vào file `index.rst` để nó hiển thị trong mục lục, sau đó chạy `make html` để cập nhật.
Sử dụng giao diện Read the Docs
Giao diện mặc định của Sphinx khá đơn giản. Để có giao diện chuyên nghiệp và hiện đại hơn, bạn có thể cài đặt theme `sphinx_rtd_theme`.
Bước 1: Cài đặt theme
pip install sphinx-rtd-theme
Bước 2: Áp dụng cấu hình
Chỉnh sửa file `docs/source/conf.py`:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
Chạy lại `make html` để thấy sự thay đổi.
Triển khai tài liệu trên Read the Docs
Để đăng tải tài liệu lên nền tảng Read the Docs, bạn cần chuẩn bị file cấu hình.
Tạo file `.readthedocs.yaml` tại thư mục gốc của dự án:
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.10"
sphinx:
configuration: docs/source/conf.py
Đẩy mã nguồn lên GitHub, sau đó đăng nhập vào readthedocs.org, kết nối repository và chạy build. Khi quá trình hoàn tất, tài liệu của bạn sẽ có thể truy cập công khai.
Xây dựng tài liệu đa ngôn ngữ (i18n)
Để hỗ trợ đa ngôn ngữ, bạn cần tạo một branch hoặc repository riêng cho ngôn ngữ đó (ví dụ: `vi`).
Bước 1: Cài đặt công cụ dịch
pip install sphinx-intl
Bước 2: Cấu hình trong `conf.py`
language = 'vi'
locale_dirs = ['locale/']
Bước 3: Trích xuất văn bản và tạo bản dịch
cd docs/source
sphinx-build -b gettext . locale
sphinx-intl update -p locale -l vi
cd ..
Bước 4: Dịch nội dung
Mở các file `.po` trong thư mục `docs/source/locale/vi/LC_MESSAGES`. Trong đó, `msgid` là nội dung gốc và `msgstr` là nơi bạn điền nội dung đã dịch.
Bước 5: Build và Deploy
Sau khi dịch xong, chạy `make html` trong thư mục `docs` để kiểm tra. Sau đó đẩy code lên repository của ngôn ngữ tương ứng và cấu hình trên Read the Docs để gán ngôn ngữ đó là một dự án con (sub-project) của dự án chính.