Viết sách bằng Sphinx

documentation

4

Ngoc Dao viết ngày 20/03/2016

Để viết tài liệu ngắn, ví dụ ngắn như bài viết này, ta. có thể dùng công cụ nhỏ xinh như Markdown. Tuy nhiên để viết tài liệu dài hơn, ví dụ dài như sách cả trăm trang, cần chia theo chương hồi, chúng ta nên dùng công cụ cao cấp hơn. Bài viết này giới thiệu công cụ Sphinx (đừng nhầm với Sphinx Search). Nó dùng reStructuredText cũng thân thiện không kém Markdown.

Sphinx được dùng nhiều trong giới Python vì nó được viết bằng Python. Tài liệu chuẩn của Python viết bằng Sphinx. Nó xuất ra được nhiều định dạng như HTML, EPUB, TeX, PDF (xuất được cả PDF tiếng Nga, Nhật, Hàn, Việt v.v.).

Một số tác phẩm tạo bằng Sphinx:

• Xitrum: tác phẩm, mã nguồn
• Akka (dùng style riêng, không dùng style mặc định): tác phẩm, mã nguồn
• Warp: tác phẩm, mã nguồn

Học cách dùng Sphinx không khó. Chỉ mất khoảng 1 tiếng xem ví dụ và đọc tài liệu hướng dẫn của Sphinx (xem các link ở trên), bạn sẽ biết cách viết và tạo ra tác phẩm cuối cùng.

Chú ý khi dùng với gh-pages

Github có tính năng pages. Trang web chứa tác phẩm của Xitrum ở trên dùng tính năng này.

Sphinx tạo ra thư mục có dấu gạch phía trước (_sources, _static). Mặc định tính năng pages của Github không kèm các thư mục này vào pages. Do đó cần thêm tập tin rỗng có tên .nojekyll vào thư mục gốc của branch gh-pages.