Cách thiết lập Sphinx để ghi lại mã Python của bạn
Sphinx là một trong những công cụ phổ biến nhất để tạo tài liệu. Trên khắp cộng đồng Python, các nhà phát triển sử dụng phần mềm mã nguồn mở và miễn phí này. Nó có thể trích xuất văn bản trực tiếp từ mã hoặc tệp đánh dấu của bạn, sau đó sử dụng nó để tạo tài liệu ở nhiều định dạng khác nhau như văn bản thuần túy, HTML, PDF và EPUB.
Mục Lục
Thiết lập Nhân sư
Trước khi bạn thiết lập Sphinx, hãy xem chức năng của nó và một số tính năng chính của nó.
Nhân sư là gì và nó làm gì?
Như đã đề cập, Sphinx là một trình tạo tài liệu. Theo mặc định, nó sử dụng ngôn ngữ đánh dấu reStructuredText (RST) nhưng thông qua tiện ích mở rộng của bên thứ ba, nó cũng có thể sử dụng Markdown, ngôn ngữ đánh dấu văn bản thuần túy phổ biến. Sau đó, nó chuyển đổi các tệp RST hoặc tệp đánh dấu này thành HTML, PDF, các trang thủ công hoặc các định dạng khác mà bạn thích.
Một số tính năng mà Sphinx bao gồm là:
- Khả năng tạo tài liệu từ mã.
- Khả năng tham khảo chéo các trang tài liệu khác nhau bằng cách sử dụng các liên kết tự động cho các chức năng, lớp, trích dẫn và thuật ngữ thuật ngữ.
- Đánh dấu cú pháp cho các khối mã.
- Hỗ trợ các chủ đề có thể thay đổi giao diện của tài liệu.
- Dễ dàng định nghĩa cây tài liệu thông qua mục lục.
- Khả năng tích hợp với các tiện ích mở rộng của bên thứ ba để thêm nhiều chức năng hơn vào tài liệu, chẳng hạn như kiểm tra đoạn mã.
Cài đặt nhân sư
Trước khi cài đặt Sphinx, hãy đảm bảo rằng bạn đã cài đặt Python 3 trong môi trường phát triển của mình. Sau đó, bạn có thể sử dụng trình quản lý gói pip để cài đặt Sphinx bằng cách chạy lệnh sau trong thiết bị đầu cuối của mình:
pip install sphinx
Điều này sẽ tải xuống và cài đặt Sphinx và các phần phụ thuộc của nó.
Sau khi cài đặt, hãy chạy lệnh sau trên dấu nhắc lệnh.
sphinx-build --version
Nếu mọi thứ hoạt động tốt, bạn sẽ thấy số phiên bản của gói Sphinx mà bạn vừa cài đặt.
Tạo một dự án nhân sư mới
Khi bạn đã cài đặt Sphinx, hãy điều hướng đến thư mục làm việc của bạn và chạy lệnh sphinx-quickstart để tạo một dự án Sphinx mới.
sphinx-quickstart
Lệnh này sẽ nhắc bạn trả lời một loạt câu hỏi về cách định cấu hình dự án Sphinx của bạn. Bạn có thể chỉ định tên dự án và sử dụng các tùy chọn mặc định cho các câu hỏi khác. Trong tương lai, bạn có thể muốn tùy chỉnh các phản hồi dựa trên dự án của mình.
Nếu bạn liệt kê nội dung của thư mục, bạn sẽ thấy lệnh này tạo một số tệp cho bạn. conf.py chứa các giá trị cấu hình và index.rst đóng vai trò là trang chào mừng trong tài liệu của bạn. Thư mục bản dựng sẽ lưu trữ tài liệu được tạo và Sphinx sử dụng Makefile (make.bat trên Windows) để xây dựng tài liệu.
Viết tài liệu bằng Sphinx
Tệp index.rst trong thư mục gốc là trang chủ của ứng dụng của bạn. Vì vậy, hãy mở nó bằng một trình soạn thảo văn bản như VS Code—hoặc bất kỳ trình soạn thảo mã miễn phí, tốt nào khác—để chỉnh sửa nó.
Bạn có thể thay đổi index.rst khi bạn thấy phù hợp nhưng một điều mà ít nhất nó phải có là chỉ thị gốc toctree (cây mục lục). Điều này rất cần thiết vì nó kết nối nhiều tệp với một hệ thống phân cấp tài liệu duy nhất.
Để thêm tài liệu vào tệp index.rst, bạn có thể sử dụng mã đánh dấu RST.
Ví dụ, hãy xem xét tệp index.rst cho mô-đun math_utils. Tệp này có thể bao gồm tổng quan ngắn gọn về mục đích của mô-đun và mục lục liên kết đến các trang khác của tài liệu.
Welcome to Math Utils
======================.. toctree::
:maxdepth: 2
Getting Started
---------------
To use this module, you'll need the following:
* Python installed.
* A text editor
Math Utils
----------
The `math-utils` module provides basic math functions like addition and
subtraction.
Bạn có thể thêm nhiều tệp .rst nếu cần. Ví dụ: bạn có thể tạo hướng dẫn đóng góp trong một tệp có tên đóng góp.rst chứa các nguyên tắc đóng góp sau.
Contributing Guide
==================We welcome contributions to our project! Here are some guidelines for
contributing:
- Fork the project on GitHub.
- Make your changes on a new branch.
- Write tests to ensure that your changes work correctly.
- Submit a pull request with your changes.
- Make any requested changes.
Thank you for contributing!
Sau đó, bạn có thể liên kết tệp này từ index.rst bằng cách thêm một phần mới vào chỉ thị toctree:
.. toctree::
:maxdepth: 2
:caption: Table of Contents
contributing
Điều này tạo ra một mục mới có tên là đóng góp trong mục lục đưa người dùng đến trang đóng góp khi được nhấp vào.
Khi bạn đã viết xong tài liệu, bước tiếp theo là xây dựng nó. Ở đây, xây dựng tài liệu có nghĩa là tạo các trang HTML, thủ công hoặc PDF từ các tệp RST.
Xây dựng tài liệu
Để xây dựng tài liệu bằng Sphinx, bạn sẽ cần chạy lệnh make html ở thư mục gốc của thư mục chứa tệp thực hiện.
make html
Bạn sẽ thấy các tệp HTML trong thư mục bản dựng. Nếu có lỗi trong quá trình xây dựng, Sphinx sẽ cho bạn biết trong thiết bị đầu cuối.
Để xem tài liệu, hãy mở tệp index.html trong trình duyệt của bạn:
Bạn sẽ có thể điều hướng đến hướng dẫn đóng góp từ mục lục.
Tùy chỉnh tài liệu
Ngay bây giờ, tài liệu có một số kiểu dáng cơ bản. Nếu bạn muốn tùy chỉnh nó, bằng cách có thể thêm màu thương hiệu hoặc thậm chí thêm chế độ tối, bạn có thể cài đặt và sử dụng các chủ đề tích hợp sẵn khác hoặc tạo chủ đề tùy chỉnh của riêng mình.
Để chứng minh, hãy thử thay đổi chủ đề thành chủ đề có tên là thiên nhiên:
- Mở tệp cấu hình Sphinx conf.py trong thư mục dự án Sphinx của bạn.
- Tìm dòng xác định tùy chọn html_theme và thay đổi nó thành nature
- Lưu tệp cấu hình và xây dựng lại tài liệu để xem các thay đổi của bạn.
Đây là giao diện của trang chủ của tài liệu.
Nếu không muốn sử dụng các chủ đề tích hợp sẵn, bạn luôn có thể sử dụng chủ đề Sphinx của bên thứ ba để thay thế.
Ghi lại mã của bạn bằng cách sử dụng Docstrings
Sphinx tạo tài liệu Python của bạn từ văn bản bạn viết trong tệp RST. Mặc dù điều này là đủ trong một số trường hợp, nhưng bạn cũng có thể muốn sử dụng các chuỗi tài liệu trong mã của mình cho nó ở cấp độ mô-đun.
Các tài liệu trực tiếp bên trong các tệp nguồn của dự án của bạn. Chúng cho phép bạn mô tả chức năng của mã, cung cấp các ví dụ và thậm chí tạo các bài kiểm tra cho các ví dụ đó. Khi bạn đã viết các chuỗi tài liệu, bạn có thể tạo tài liệu từ chúng bằng Sphinx.