Làm cách nào để tham chiếu tham số hàm Python được ghi lại bằng cách sử dụng đánh dấu Sphinx?

Question

Tôi muốn tham chiếu một tham số chức năng được ghi chép trước đó ở nơi khác trong một chuỗi tài liệu Python. Hãy xem xét ví dụ sau đây (phải thừa nhận hoàn toàn nhân tạo):

def foo(bar): 
    """Perform foo action 
    :param bar: The bar parameter 
    """ 

    def nested(): 
     """Some nested function that depends on enclosing scope's bar parameter. 
     I'd like to reference function foo's bar parameter here 
     with a link, is that possible?""" 
     return bar * bar 

    # ... 
    return nested() 

Có cách đơn giản để nhúng tham chiếu tham số sử dụng đánh dấu Sphinx hoặc điều này xảy ra tự động không?

(Tôi là một newbie Sphinx hoàn tất. Tôi đã quét các tài liệu Sphinx và đã không tìm thấy câu trả lời cho câu hỏi này, hoặc một ví dụ chứng minh đánh dấu thích hợp.)

Answer 1

Tôi vừa xây dựng tiện ích mở rộng để hoàn thành tác vụ này. Cho đến nay nó có vẻ là làm việc với xây dựng HTML độc lập và bổ sung với readthedocs (sau khi một số chỉnh thêm).

tiện ích mở rộng có sẵn tại: https://pypi.python.org/pypi/sphinx-paramlinks/.

Tôi đang triển khai nó ngay bây giờ cho các dự án Alembic và SQLAlchemy. (sample).

Tôi không đồng ý với đề xuất liên kết với thông số có nghĩa là tài liệu quá dài. Thư viện chuẩn Python là một ví dụ kém ở đây vì các hàm stdlib nhất thiết phải là chi tiết và đơn giản. Phần mềm hoàn thành nhiệm vụ thô sơ hơn, trong đó một hàm duy nhất chạy trên đầu một vấn đề phức tạp cần giải quyết, thường sẽ có các tham số yêu cầu giải thích nhiều hơn; giải thích này thường khá có giá trị như giải pháp cho một vấn đề cụ thể ở nơi khác, và do đó có thể liên kết với nó là rất quan trọng.

Answer 2

Nếu bạn đang tìm kiếm một cách để liên kết trực tiếp với định nghĩa bar của foo thì tài liệu của bạn quá dài hoặc bạn yêu cầu người đọc bỏ qua rừng cho một cây hoặc một số kết hợp của cả hai.

Lấy một ví dụ từ defaultdict Examples:

Setting the :attr:`default_factory` to :class:`int` makes the 
:class:`defaultdict` useful for counting (like a bag or multiset in other 
languages): 

nếu tôi không thể bị làm phiền để đọc năm câu vào collections.defaultdict để tìm ra ý nghĩa của default_factory tôi có lẽ không xứng đáng để được dẫn ở đó.

Lưu ý rằng cú pháp tham khảo thuộc tính cũng giống như ở phần trên:

The first argument provides the initial value for the :attr:`default_factory` 
attribute; it defaults to ``None``. 

nhưng có vẻ như Sphinx không đạt được ra khỏi phạm vi phần hiện tại và do đó làm cho các tài liệu tham khảo sau dưới dạng văn bản theo kiểu chứ không phải là neo. Nó sẽ không làm tôi ngạc nhiên nếu điều này là cố ý.

Answer 3

Không có cách nào đơn giản để có tham chiếu trực tiếp đến tham số của hàm có số sphinx và tôi không biết phần mở rộng của vấn đề này.

documentation of the python domain giải thích đối tượng nào có thể được tham chiếu chéo.

Một cách tốt để cung cấp cho người dùng một tham chiếu đến tham số bar chức năng foo sẽ

See parameter ``bar`` in :func:`foo`. 

Có lẽ một tham chiếu trực tiếp sẽ có thể bằng cách viết một phần mở rộng.