Cách tạo chỉ thị tùy chỉnh trong Sphinx

Question

Tôi hiện đang ghi lại một API còn lại được viết bằng Python. Tất cả tài liệu của dự án được tạo ra bằng cách sử dụng Sphinx, và cho REST API tôi muốn tạo ra một số chỉ thị đặc biệt. Ví dụ: giả sử tôi có tài nguyên này được xác định:

@resource("/user/<email>", method="GET") 
def user_details (email): 
    """ Returns detailed information about a user account. 

    :resource GET: /user/<email> 
    :query_param a_param: Some kind of query param. 
    """ 
    # Do stuff and return user details 

Về cơ bản, tài liệu đó trông như thế nào. Tôi muốn có thể tạo ra một chỉ thị cho Sphinx định dạng một hoặc nhiều trong số :query_param ...: giống như nó với :param: thông thường.

Tôi đã tìm thấy cách tạo vai trò, nhưng chúng chỉ hoạt động nội tuyến chứ không phải cho các khối dữ liệu.

Làm thế nào tôi nên thực hiện việc này?

Answer 1

Nhân sư có thể được mở rộng với chỉ thị tùy chỉnh qua "Sphinx Extensions". Tức là, bạn sẽ cần phải triển khai một phần mở rộng Sphinx cung cấp chỉ thị tùy chỉnh query_param và thêm phần mở rộng này vào dự án Sphinx của bạn.

Tài liệu nhân sư cung cấp a tutorial về việc triển khai tiện ích, trong đó chúng thực hiện chỉ thị tùy chỉnh thực sự.

tham khảo:

http://sphinx.pocoo.org/extensions.html

http://sphinx-doc.org/extdev/index.html#dev-extensions