Python Sphinx tham khảo tên dài

Question

Tôi đang làm tài liệu cho mô-đun Python của mình (sử dụng Sphinx và reST), và tôi thấy rằng khi tham chiếu chéo các đối tượng Python khác (mô đun, lớp, hàm, v.v.) tên kết thúc là cực kỳ dài. Thường thì nó dài hơn 80 ký tự, mà tôi muốn tránh bằng mọi giá.

Dưới đây là một ví dụ:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    :class:`module1.module2.module3.module4.module5.ReallyLongExampleClassName` 

    ''' 

Vấn đề là khi tạo tài liệu cho lớp ReallyLongExampleClassName, tôi tạo ra nó cho đường dẫn đầy đủ tên module1.module2.module3.module4.module5.ReallyLongExampleClassaName .

Tôi tự hỏi liệu có cách nào để giải quyết vấn đề này không? Tôi đã thử các phương pháp sau, không thành công:

1) Thêm ngắt dòng ở giữa tên mô-đun. Ví dụ:

:class:`module1.module2.module3.module4. 
module5.ReallyLongExampleClassName` 

2) Tham chiếu tên lớp theo cách khác (nhưng vẫn có thể nhập bằng Python). Ví dụ:

:class:`module1.module2.ReallyLongClassName` 

Tôi tin rằng vì tài liệu cho ReallyLongClassName được gắn với tên đường dẫn đầy đủ nên Sphinx không thể tương quan với phiên bản rút gọn với phiên bản đầy đủ.

Mọi trợ giúp sẽ được đánh giá cao.

Sửa 04/05/2012:

Theo câu trả lời/đề nghị của j13r (xem dưới đây) Tôi thử như sau:

:class:`module1.module2.module3.module4.module5\ 
ReallyLongExampleClassName` 

Và điều này làm việc thành công. Chỉ báo trước để làm việc này, đó là dòng thứ hai không được có dấu cách trước nó (điều này khá bực bội khi sử dụng nó trong một docstring). Vì vậy, để làm ví dụ ban đầu của tôi hoạt động, nó sẽ trông giống như:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    :class:`module1.module2.module3.module4.module5.\ 
ReallyLongExampleClassName` 

    ''' 

Đẹp và xấu xí. Nếu bạn đã đặt dấu cách trước "ReallyLongExampleClassName" để thụt lề nó với cùng cấp như dòng trên nó, đầu ra sẽ bao gồm các khoảng trắng và do đó Sphinx sẽ cố gắng tham khảo một cái gì đó như "module1.module2.module3.module4.module5. ReallyLongExampleClassName. "

Tôi cũng nên lưu ý rằng tôi đã thử hai biến thể khác của này, mà không làm việc:

# Note: Trying to put a space before the '\' 
    :class:`module1.module2.module3.module4.module5. \ 
ReallyLongExampleClassName` 

    # Note: Trying to leave out the '\' 
    :class:`module1.module2.module3.module4.module5. 
ReallyLongExampleClassName` 

tôi đang tìm kiếm một giải pháp mà không liên quan đến phá hủy các định dạng của docstring, nhưng tôi cho rằng nó sẽ làm ... Tôi nghĩ rằng tôi thực sự thích một dòng mà đi qua 80 ký tự này.

Nhờ j13r cho câu trả lời!

Answer 1

Theo tài liệu Sphinx (http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects), bạn có thể sử dụng một dấu chấm trước lớp mục tiêu của bạn:

:class:`.ReallyLongExampleClassName` 

hoặc

:class:`.module5.ReallyLongExampleClassName` 

và để tìm kiếm nhân sư cho lớp học:

... nếu tên được đặt trước dấu chấm và không tìm thấy kết quả chính xác, mục tiêu được chọn làm hậu tố và tất cả tên đối tượng có hậu tố đó được tìm kiếm . Ví dụ: py: meth: .TarFile.close tham chiếu hàm tarfile.TarFile.close(), ngay cả khi mô-đun hiện tại không phải là tarfile. Vì điều này có thể trở nên mơ hồ, nếu có nhiều hơn một trận đấu có thể, bạn sẽ nhận được cảnh báo từ Nhân sư.

Answer 2

Đục hoang dã trong bóng tối.Có lẽ việc này:

:class:`module1.module2.module3.module4.\ 
module5.ReallyLongExampleClassName` 

Nó sẽ là Python hợp lệ

import scipy.\ 
stats 

Answer 3

Bạn có thể sử dụng ~ làm tiền tố, nó thực hiện chính xác những gì bạn muốn.

http://sphinx-doc.org/markup/inline.html#xref-syntax

Answer 4

chiến lược khác là sử dụng phần còn lại Substitutions. Điều này sẽ cho phép bạn tiết kiệm không gian hơn trong văn bản bằng cách gọi :class: tham chiếu chéo sau:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    |ReallyLongExampleClassName| 

    .. |ReallyLongExampleClassName| replace:: 
            :class:`.ReallyLongExampleClassName` 

    ''' 

Nếu bạn đang đề cập đến cùng lớp trong nhiều tập tin của bạn, bạn thay vì có thể đặt thay thế trong bạn Tệp tin Sphinx conf.py, sử dụng cài đặt rst_epilog. Từ các tài liệu Sphinx:

rst_epilog

Một chuỗi reStructuredText đó sẽ được đưa vào cuối mỗi tập tin nguồn mà được đọc. Đây là nơi thích hợp để thêm các thay thế cần có sẵn trong mỗi tệp. Ví dụ:

rst_epilog = """ 
.. |psf| replace:: Python Software Foundation 
""" 

Phiên bản mới 0.6.

Sau đó docstring của bạn sẽ chỉ được:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    |ReallyLongExampleClassName| 

    '''