Phát ra reStructuredText từ sphinx autodoc?

Question

CPython không sử dụng autodoc cho tài liệu của nó - chúng tôi sử dụng văn xuôi viết tay.

Đối với PEP 3144 (mô-đun ipaddress), tôi muốn sử dụng sphinx-apidoc để tạo tài liệu tham chiếu ban đầu. Điều đó có nghĩa tôi muốn chạy một hoạt động hai-pass:

1. Sử dụng Sphinx-apidoc phát ra một dự án Sphinx cho các mô-đun mà phụ thuộc vào autodoc

2. Chạy một người thợ xây nhân sư mà tạo ra file nguồn reStructuredText mới , với tất cả các chỉ thị autodoc thay thế bằng nội dung inline reStructuredText và đánh dấu sản xuất cùng một sản lượng

bước đầu tiên là đơn giản, nhưng tôi không có ý tưởng làm thế nào để làm bước thứ hai và thậm chí không thể nghĩ ra tốt cách tìm kiếm f hoặc bất kỳ dự án hiện có nào dọc theo các tuyến này.

Answer 1

Tôi đã có cùng một vấn đề và trong một lần tạo tài liệu tôi đã sử dụng giải pháp khá xấu xí để vá Nhân sư, xem Make Sphinx generate RST class documentation from pydoc.

Answer 2

Không phải là một câu trả lời đầy đủ, nhiều hơn hoặc ít hơn một điểm khởi đầu:

autodoc dịch chỉ thị ô tô để chỉ thị python. Vì vậy, người ta có thể sử dụng các sự kiện autodoc để có được các chỉ thị python dịch.

Ví dụ, nếu bạn đã sau mymodule.py:

#!/usr/bin/env python 
# -*- coding: utf-8 -*- 

""" 
This is my module. 
""" 

def my_test_func(a, b=1): 
    """This is my test function""" 
    return a + b 

class MyClass(object): 
    """This is my class""" 

    def __init__(x, y='test'): 
     """The init of my class""" 
     self.x = float(x) 
     self.y = y 

    def my_method(self, z): 
     """This is my method. 

     :param z: a number 
     :type z: float, int 
     :returns: the sum of self.x and z 
     :rtype: float 
     """ 
     return self.x + z 

sphinx-apidoc sẽ tạo

mymodule Module 
=============== 

.. automodule:: mymodule 
    :members: 
    :undoc-members: 
    :show-inheritance: 

Việc gia hạn sau đây (hoặc bổ sung để conf.py):

NAMES = [] 
DIRECTIVES = {} 

def get_rst(app, what, name, obj, options, signature, 
      return_annotation): 
    doc_indent = ' ' 
    directive_indent = '' 
    if what in ['method', 'attribute']: 
     doc_indent += ' ' 
     directive_indent += ' ' 
    directive = '%s.. py:%s:: %s' % (directive_indent, what, name) 
    if signature: # modules, attributes, ... don't have a signature 
     directive += signature 
    NAMES.append(name) 
    rst = directive + '\n\n' + doc_indent + obj.__doc__ + '\n' 
    DIRECTIVES[name] = rst 

def write_new_docs(app, exception): 
    txt = ['My module documentation'] 
    txt.append('-----------------------\n') 
    for name in NAMES: 
     txt.append(DIRECTIVES[name]) 
    print '\n'.join(txt) 
    with open('../doc_new/generated.rst', 'w') as outfile: 
     outfile.write('\n'.join(txt)) 

def setup(app): 
    app.connect('autodoc-process-signature', get_rst) 
    app.connect('build-finished', write_new_docs) 

sẽ cung cấp cho bạn :

My module documentation 
----------------------- 

.. py:module:: mymodule 


This is my module. 


.. py:class:: mymodule.MyClass(x, y='test') 

    This is my class 

    .. py:method:: mymodule.MyClass.my_method(z) 

     This is my method. 

     :param z: a number 
     :type z: float, int 
     :returns: the sum of self.x and z 
     :rtype: float 


.. py:function:: mymodule.my_test_func(a, b=1) 

    This is my test function 

Tuy nhiên, không có sự kiện, khi bản dịch được hoàn thành, Vì vậy, việc xử lý tiếp theo được thực hiện bằng autodoc phải được điều chỉnh phù hợp với tài liệu tại đây.