Sphinx là là một công cụ giúp bạn dễ dàng tạo tài liệu thông minh và đẹp mắt, được viết bởi Georg Brandl.
Ban đầu nó được tạo cho tài liệu python, và nó là cơ sở cho tài liệu của các dự án phần mềm bằng nhiều ngôn ngữ.
Các tính năng:
-
Output formats: HTML, LaTex, ePub, Texinfo, mamual pages, plain text
-
Extensive cross-reference: Đánh dấu ngữ nghĩa và liên kết tự động cho functions, classes, citations, glossary terms và các thông tin tương tự.
-
Hierarchical structure: Dễ dàng định nghĩa document tree, với các liên kết tự động đến nhánh anh em, cha và con.
-
Automatic indices: index chung như một ngôn ngữ cụ thể.
-
Code handling: Tự động highlight sử dụng công cụ Pygments.
-
Extensions: Tự động kiểm tra code snippets, bao gồm API docs,…more
-
Contributed extensions: Hơn 50 extensions contributed by users
Sphinx sử dụng reStructuredText nhưng là ngôn ngữ để định dạng.
First step
Install Sphinx:
$ pip install -U Sphinx
-
Đến thư mục của project.
-
Tạo và activate môi trường Python.
$ virtualenv -p python3 <name of virtualenv>
$ source <name of virtualenv>/bin/activate
-
Tạo folder.
$ mkdir docs
$ cd docs
-
Setup Sphinx
$ sphinx-quickstart
Fill các thông tin cần thiết.
-
Separate source and build directories (y/n) [n]: y -→ Giúp tạo ra 2 folder build và source bên trong folder docs.
-
Sau bước này trong folder trông sẽ như sau:
Sau khi hoàn thành nhanh các bước. Ta thấy như sau:
File index.rst là tập tài liệu ban đầù của bạn. Mở rộng thư mục bằng cách add thêm file.rst bổ sung vào thư mục này.
-
Build.
$ make html
-
source/index viết toctree
-
Include file README.md
-
Rebuilde.
$ make html
-
Check tại build/html/index.html