Override khai báo hàm trong autodoc cho Sphinx

Question

Tôi có một mô-đun mà đi một cái gì đó như thế này:

#!/usr/bin/env python 

#: Documentation here. 
#: blah blah blah 
foobar = r'Some really long regex here.' 

def myfunc(val=foobar): 
    '''Blah blah blah''' 
    pass 

... và tôi có một tập tin .rst mà đi một cái gì đó như thế này:

:mod:`my_module` Module 
----------------------- 

..automodule:: my_module 
    :members: 
    :private-members: 
    :show-inheritance: 

Khi Tôi tạo tài liệu, tôi nhận được tệp html có đoạn mã như sau:

mymodule.foobar. foobar = 'Một số regex absurdly dài và xấu xí ở đây'

thêm tài liệu ở đây

mymodule. myfunc (val = 'Một số regex absurdly dài và xấu xí ở đây')

blah blah blah

Dựa trên stackoverflow post này, tôi nghĩ rằng tôi có thể thay đổi nó bằng cách thay đổi mô-đun của tôi để:

#!/usr/bin/env python 

#: .. data:: my_module.foobar 
#: Extra documentation here 
foobar = 'Some really long regex here.' 

def myfunc(val=foobar): 
    '''.. function:: my_module.myfunc(val=foobar) 

    Blah blah blah''' 
    pass 

... nhưng điều đó không thực hiện thủ thuật và chỉ thêm chữ ký tôi muốn dưới chữ cái xấu xí như một phần của cơ thể. Có ai biết làm thế nào tôi có thể ghi đè đúng cách này?

(Tôi đang sử dụng Sphinx v1.1.3, btw.)

Answer 1

Bạn có một biến mô-đun cấp được sử dụng như giá trị mặc định của một đối số từ khóa trong một hàm. Sphinx hiển thị giá trị (thay vì tên) của biến đó trong chữ ký hàm. Vấn đề này được thảo luận trong another question và OP cũng đã gửi an issue ticket tại GitHub về vấn đề này.

Tuy nhiên, bạn có thể làm việc xung quanh này theo hai cách:

1. Override chữ ký trong file .rst bằng cách sử dụng autofunction, như được giải thích trong the answer cho câu hỏi liên quan.

2. Nếu dòng đầu tiên của chuỗi tài liệu trông giống như chữ ký và nếu biến cấu hình autodoc_docstring_signature được đặt thành True (theo mặc định) thì Sphinx sẽ sử dụng dòng đó làm chữ ký.

   Vì vậy, nếu bạn có một docstring trông như sau,

   def myfunc(val=foobar): 
       '''myfunc(val=foobar) 
   
       Blah blah blah''' 
       pass 
   

   nó nên làm việc theo cách bạn muốn nó.

   Trong câu hỏi, bạn có dòng đầu tiên này trong docstring:

   .. function:: my_module.myfunc(val=foobar) 
   

   này không hoạt động bởi vì nó không giống như một chữ ký hợp lệ.