Cách tự động để chuyển từ định dạng chuỗi tài liệu của epydoc sang định dạng chuỗi tài liệu nhân sư?

Question

Tôi đã có một dự án mà tôi đã ghi lại bằng epydoc. Bây giờ tôi đang cố gắng chuyển sang nhân sư. Tôi đã định dạng tất cả các tài liệu của mình cho epydocs, bằng cách sử dụng B {}, L {} vv để bolding, liên kết và tương tự, và sử dụng @param, @return, @raise vv để giải thích đầu vào, đầu ra, ngoại lệ và các lượt thích.

Vì vậy, bây giờ tôi đang chuyển sang nhân sư, nó mất tất cả các tính năng này. Có cách nào tự động để chuyển đổi docstrings định dạng cho epydocs để docstrings định dạng cho nhân sư?

Answer 1

Để mở rộng câu trả lời của Kevin Horn, tài liệu có thể được dịch nhanh chóng trong trình xử lý sự kiện được kích hoạt bởi sự kiện autodoc-process-docstring.

Dưới đây là một minh chứng nhỏ (hãy thử bằng cách thêm mã vào conf.py). Nó thay thế các ký tự @ trong một số phổ biến Epytext fields với :, được sử dụng trong Sphinx fields tương ứng.

import re 

re_field = re.compile('@(param|type|rtype|return)') 

def fix_docstring(app, what, name, obj, options, lines): 
    for i in xrange(len(lines)): 
     lines[i] = re_field.sub(r':\1', lines[i]) 

def setup(app): 
    app.connect('autodoc-process-docstring', fix_docstring) 

Answer 2

Về lý thuyết, bạn có thể viết phần mở rộng Sphinx sẽ bắt bất kỳ sự kiện nào được kích hoạt khi một chuỗi tài liệu được đọc (source_read, có thể?) Và dịch các tài liệu khi đang di chuyển.

tôi nói về mặt lý thuyết bởi vì:

1. tôi đã có nghĩa là để viết một điều như vậy trong một thời gian rất dài, nhưng đã không được quản lý để có được xung quanh để nó được nêu ra.
2. Dịch các nội dung như thế này luôn khó hơn.

Bạn cũng có thể thử thay thế tất cả các tài liệu trong mã của mình bằng trình dịch tương tự bên ngoài Sphinx, có thể sử dụng mô-đun ast hoặc tương tự.

Answer 3

Pyment là công cụ có thể chuyển đổi tài liệu Python và tạo bộ xương thiếu. Nó có thể quản lý Google, Epydoc (javadoc phong cách), Numpydoc, reStructuredText (nghỉ ngơi, Sphinx mặc định) các định dạng docstring.

Nó chấp nhận một tệp hoặc một thư mục (khám phá cũng các thư mục con). Đối với mỗi tệp, nó sẽ nhận dạng từng định dạng docstring và chuyển đổi nó thành định dạng mong muốn. Cuối cùng, một bản vá sẽ được tạo để áp dụng cho tệp.

Để chuyển đổi dự án của bạn:

• cài đặt Pyment

Loại như sau (bạn có thể sử dụng một virtualenv):

$ git clone https://github.com/dadadel/pyment.git 
$ cd pyment 
$ python setup.py install 

• chuyển đổi từ Epydoc để Nhân sư

Bạn có thể chuyển đổi dự án của bạn sang định dạng Sphinx (phần còn lại), là định dạng đầu ra mặc định, bằng cách thực hiện:

$ pyment /my/folder/project