Có thể ẩn các đối số hàm Python trong Sphinx không?

Question

Giả sử tôi có chức năng sau đó được diễn tả trong Numpydoc style, và các tài liệu hướng dẫn là tự động được tạo ra với Sphinxautofunction directive:

def foo(x, y, _hidden_argument=None): 
    """ 
    Foo a bar. 

    Parameters 
    ---------- 
    x: str 
     The first argument to foo. 
    y: str 
     The second argument to foo. 

    Returns 
    ------- 
    The barred foo. 

    """ 
    if _hidden_argument: 
     _end_users_shouldnt_call_this_function(x, y) 
    return x + y 

Tôi không muốn quảng cáo đối số ẩn như một phần của API công cộng của tôi , nhưng nó xuất hiện trong tài liệu được tạo tự động của tôi. Có cách nào để nói với Sphinx bỏ qua một đối số cụ thể cho một hàm, hoặc (thậm chí tốt hơn) làm cho nó tự động bỏ qua các đối số với một dấu gạch dưới hàng đầu?

Answer 1

Tôi không nghĩ rằng có một tùy chọn cho điều đó trong Sphinx. Một cách có thể để thực hiện điều này mà không cần phải xâm nhập vào mã, là sử dụng chữ ký tùy chỉnh.

Trong trường hợp này, bạn cần một cái gì đó như:

.. autofunction:: some_module.foo(x, y) 

này sẽ ghi đè lên danh sách tham số của hàm và ẩn đối số không mong muốn trong doc.

Answer 2

Có thể chỉnh sửa chữ ký hàm trong trình xử lý cho sự kiện autodoc-process-signature.

Thông số signature của trình xử lý sự kiện giữ chữ ký; một chuỗi có dạng (parameter_1, parameter_2). Trong đoạn mã dưới đây, split() được sử dụng để loại bỏ các tham số cuối cùng của một hàm:

hidden = "_hidden_argument" 

def process_sig(app, what, name, obj, options, signature, return_annotation): 
    if signature and hidden in signature: 
     signature = signature.split(hidden)[0] + ")" 
    return (signature, return_annotation) 

def setup(app): 
    app.connect("autodoc-process-signature", process_sig) 

Kết quả là tài liệu sẽ hiển thị các chữ ký của các chức năng trong câu hỏi như foo(x, y) thay vì foo(x, y, _hidden_argument=None).