Có bất kỳ lựa chọn thay thế thực sự nào cho reStructuredText cho tài liệu Python không?

Question

Tôi đang bắt đầu một dự án Python nguồn mở ngay và tôi đang cố gắng quyết định trước cách viết tài liệu của mình. Câu trả lời rõ ràng sẽ sử dụng reStructuredText và Sphinx với autodoc, bởi vì tôi thực sự giống như ý tưởng chỉ cần viết tài liệu của tôi một cách đơn giản trong tài liệu của tôi sau đó có Sphinx tự động xây dựng một tài liệu API cho tôi.

Vấn đề là cú pháp reStructuredText mà nó sử dụng - tôi nghĩ rằng nó hoàn toàn không đọc được trước khi nó được hiển thị. Ví dụ:

 
:param path: The path of the file to wrap 
:type path: str 
:param field_storage: The :class:`FileStorage` instance to wrap 
:type field_storage: FileStorage 
:param temporary: Whether or not to delete the file when the File instance 
    is destructed 
:type temporary: bool 

Bạn phải thực sự chậm và mất vài phút để thực hiện bất kỳ cảm giác ra khỏi mớ bòng bong mà cú pháp. Tôi thích nhiều hơn nữa cách Google (Google Python Style Guide), trong đó đối với bên trên trông như thế này:

 
Args: 
    path (str): The path of the file to wrap 
    field_storage (FileStorage): The FileStorage instance to wrap 
    temporary (bool): Whether or not to delete the file when the File 
     instance is destructed 

Way đẹp hơn! Nhưng dĩ nhiên, Sphinx sẽ không có gì trong số đó và hiển thị tất cả văn bản sau "Args:" trong một hàng dài.

Vì vậy, để tóm tắt - trước khi tôi đi và làm hỏng cơ sở mã của tôi với cú pháp reStructuredText này tôi muốn biết nếu có bất kỳ lựa chọn thay thế thực sự để sử dụng nó và Sphinx, ngắn chỉ cần viết tài liệu API của riêng tôi. Ví dụ: có phần mở rộng cho Sphinx xử lý kiểu chuỗi tài liệu của Hướng dẫn kiểu Google không?

Answer 1

Tôi không nghĩ rằng có điều gì đó tốt hơn sphinx để ghi lại các dự án python tại thời điểm này.

Để có một chuỗi ngắn hơn, lựa chọn ưa thích của tôi là sử dụng sphinx cùng với numpydoc. Dựa trên ví dụ của bạn này sẽ như thế nào:

def foo(path, field_storage, temporary): 
    """This is function foo 

    Parameters 
    ---------- 
    path : str 
     The path of the file to wrap 
    field_storage : :class:`FileStorage` 
     The :class:`FileStorage` instance to wrap 
    temporary : bool 
     Whether or not to delete the file when the File instance 
     is destructed 

    Returns 
    ------- 
    describe : type 
     Explanation 
    ... 

    Examples 
    -------- 
    These are written in doctest format, and should illustrate how to 
    use the function. 

    >>> a=[1,2,3] 
    >>> print [x + 3 for x in a] 
    [4, 5, 6] 
    ... 
    """ 

    pass 

(một ví dụ đầy đủ là Here), đầu ra HTML sẽ trông giống như this

Tôi nghĩ rằng cấu trúc của đầu tiên-file là rõ ràng và dễ đọc hơn. guide cung cấp thêm một số thông tin và quy ước. Tiện ích mở rộng numpydoc cũng hoạt động với autodoc.

Answer 2

Python làm cho nội dung của các tài liệu có sẵn dưới dạng thuộc tính __doc__ được gắn với đối tượng hàm/lớp/biến.

Vì vậy, bạn có thể trivially viết một chương trình Python chuyển đổi tài liệu từ bất kỳ định dạng nào bạn thích thành bất kỳ định dạng nào bạn muốn. Bạn thậm chí có thể sử dụng kiểu dáng Javadoc, hoặc XML, hoặc bất cứ thứ gì.

Ngẫu nhiên, vì Sphinx được viết bằng Python, làm cho nó lấy đầu vào không RST chỉ là vấn đề viết một lượng nhỏ mã Python.

Answer 3

Trên thực tế, reStructuredText cũng như hướng dẫn kiểu từ PEP8 áp dụng chủ yếu cho việc mã hóa thư viện chuẩn của Python, mặc dù rất nhiều lập trình viên của bên thứ ba tuân thủ điều đó.

Tôi đồng ý với bạn rằng phong cách của Google đối số tốt hơn nhiều so với phối cảnh trong mã. Nhưng bạn cũng có thể generate such docstring with sphinx, with the new lines and indentation preserved. Nó không xuất ra tốt đẹp như with a more sphinxy formatting.

Dù sao, bạn không phải sử dụng nhân sư, và nhân tiện, mô-đun của autodoc nhân sư chắc chắn chỉ là một phần nhỏ của nó. Bạn hầu như có thể sử dụng bất kỳ trình tạo tài liệu nào có khả năng truy xuất nội dung của tài liệu, chẳng hạn như Epydoc (hỗ trợ epytext cũng như reStructuredText, Javadoc or Plaintext) hoặc pydoctor hoặc thậm chí phổ biến hơn như Doxygen. Tuy nhiên, chắc chắn, nhân sư là khá pythonic, rất thuận tiện để sử dụng với Python, và làm cho mã của bạn phù hợp với hệ sinh thái của Python. Tôi nghĩ rằng bạn là not the only one người nghĩ rằng đây là một "thiếu". Có lẽ họ sẽ đưa những khiếu nại này vào tài khoản trong tương lai, hoặc có lẽ bạn thậm chí có thể cân nhắc việc tự mình modyfying mô-đun autodoc, không phải là rất khó, nó là bằng Python, nó sẽ là một bài tập tốt.

Answer 4

Bạn có thể viết tài liệu ở bất kỳ định dạng nào bạn muốn. Tuy nhiên, vì lợi ích của mọi lập trình viên Python khác, tốt nhất nên sử dụng đánh dấu và các công cụ mà họ đã biết. Cuộc sống của họ dễ dàng hơn nếu bạn dính vào reST và Sphinx.

Answer 5

Tôi sử dụng epydoc và không phải nhân sư, vì vậy câu trả lời này có thể không áp dụng.

Cú pháp reStructuredText mà bạn mô tả cho các phương pháp và chức năng ghi tài liệu không phải là duy nhất có thể. Cho đến nay, tôi thích mô tả các thông số sử dụng một consolidated definition list, mà là rất tương tự như cách Google:

:Parameters: 
    path : str 
    The path of the file to wrap 
    field_storage: FileStorage 
    The FileStorage instance to wrap 
    temporary: bool 
    Whether or not to delete the file when the File instance is destructed 

tôi sẽ cố gắng hiểu xem sphix hỗ trợ nó. Nếu nó không bạn cũng có thể xem xét sử dụng epydoc chỉ cho rằng (mặc dù nó không phải là chủ động maintaned ngay bây giờ).

Answer 6

bạn chỉ cần bắt đầu một dòng mới và thêm một lần nhấn sau mỗi tên biến. Sau đó, nó được kết xuất trong một vài dòng với tên biến đậm consucutive:

Args: 
    path (str): 
     The path of the file to wrap 
    field_storage (FileStorage): 
     The FileStorage instance to wrap 
    temporary (bool): 
     Whether or not to delete the file when the File 
     instance is destructed 

Answer 7

tôi đã tạo ra một Sphinx extension rằng phân tích cả hai phong cách Google và docstrings phong cách NumPy, và chuyển đổi chúng sang reStructuredText chuẩn.

Để sử dụng nó, chỉ cần cài đặt nó:

$ pip install sphinxcontrib-napoleon 

Và kích hoạt nó trong conf.py:

# conf.py 

# Add autodoc and napoleon to the extensions list 
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon'] 

Nhiều tài liệu về napoleon here.