Bạn nhìn một bit litte bị nhầm lẫn ở đây. Nhân sư không thực sự là một máy phân tích cú pháp. Mã Python của bạn phải được chạy để làm cho Sphinx có thể nắm bắt được các tài liệu. Đó là lý do tại sao đổi tên các tệp mở rộng thành ".py" không có tác dụng.
Vâng, tôi đã làm việc với Sphinx và Cython gần đây, và muốn chia sẻ kinh nghiệm của tôi ... Đây là quy trình chi tiết đầy đủ để tự động tạo tài liệu html cho phần mở rộng Cython đã biên dịch từ docstrings:
[Lưu ý: tôi sử dụng Sphinx 1.1.3 và 0.17.4 Cython]
Trước hết, sử dụng "docstrings" của Python (với tất cả những hạn chế nó có thể có - bằng ví dụ, bạn không thể mô tả một nhà xây dựng.Xem thông số docstrings) trong mã Cython của bạn:
cdef class PyLabNode:
"""
This is a LabNode !!!
"""
cdef LabNode* thisptr
cdef PyLabNetwork network
def __cinit__(self):
self.thisptr = new LabNode()
def __dealloc__(self):
if self.thisptr:
del self.thisptr
def SetNetwork(self, PyLabNetwork net):
"""
Set the network !!!
"""
self.network = net
Và biên dịch lại "yourextension.so".
Sau đó chạy "sphinx-quickstart" và trả lời các câu hỏi. Đừng quên nói có khi được yêu cầu cho "autodoc". Điều này sẽ tạo ra "Makefile", tệp "index.rst" và tệp "conf.py".
"conf.py" cuối cùng này đã được chỉnh sửa để nói Sphinx được tìm module của bạn:
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../../parent/dir/of/yourextension/'))
Các tập tin "index.rst" phải được thay đổi nội dung cũng như để nói mà mô-đun có thể phân tích:
Contents:
.. toctree::
:maxdepth: 2
.. automodule:: yourextension
:members:
:undoc-members:
:show-inheritance:
Cuối cùng xây dựng các tài liệu bằng cách thực hiện:
$ make html
Đó là đủ cho tôi (Tôi đã nhận được tập hợp các tệp html kết quả trong thư mục ".../_ build/html /"). Có thể là Sphinx và Cython đã phát triển kể từ khi câu hỏi trước được hỏi, nhưng tôi không có vấn đề "chữ ký" nào để giải quyết. Không có chỉ thị Cython cụ thể để sử dụng, cũng không sửa chữa để áp dụng cho Sphinx ...
Hy vọng điều này sẽ hữu ích.
EDIT: Vâng, tôi muốn nhận lại lời nói của mình. Tôi gặp phải vấn đề "Dan" đã được đề cập đến liên quan đến "embedsignature" vấn đề trong khi sử dụng Epydoc (vì vậy tôi cho rằng đây là một vấn đề với Sphinx là tốt). Việc kích hoạt chỉ thị trình biên dịch này không gửi các chữ ký tương thích python anyway:
PyLabNode.SetNetwork(self, PyLabNetwork net)
Điều này có 2 nhược điểm: Ký pháp chấm cho tiền tố lớp và tham số đã nhập.
Cuối cùng, cách duy nhất tôi có thể tìm ra để gửi những người đúng là viết một chữ ký phù hợp tại dòng đầu tiên của chuỗi doc như vậy:
def SetNetwork(self, PyLabNetwork net):
"""
SetNetwork(self, net)
Set the net !!!
@param self: Handler to this.
@type self: L{PyLabNode}
@param net: The network this node belongs to.
@type net: L{PyLabNetwork}
"""
self.network = net
Hy vọng điều này có thể giúp cả hai Sphinx và người dùng Epydoc ...
EDIT: liên quan đến __cinit__, tôi đã có thể tạo ra thành công với doc Epidoc (không thử với Sphinx) bằng cách nhân đôi mô tả , Như thế này:
# For Epydoc only (only used for docstring)
def __init__(self, sim):
"""
__init__(self, sim)
Constructor.
@param sim: The simulator this binding is attached to.
@type sim: L{PyLabSimulatorBase}
"""
# Real Cython init
def __cinit__(self, PyLabSimulatorBase sim):
self.thisptr = new LabNetBinding()
self.sites = []
simulator = sim
Về Sphinx, param nên được ghi chép trong tài liệu hướng dẫn lớp học, không phải trong constructor, vì vậy nó sẽ trông tốt trong tài liệu được tạo. –