对于Python文档，reStructuredText有什么真正的替代方法吗？ [英] Are there any real alternatives to reStructuredText for Python documentation?

问题描述

我刚刚开始一个开源的Python项目，我想提前决定如何编写我的文档。明显的答案是使用reStructuredText和Sphinx与autodoc，因为我真的像在我的文档中简单地正确记录我的代码的想法，然后让Sphinx为我自动构建一个API文档。

问题是它使用的reStructuredText语法 - 我认为它在渲染之前完全不可读。例如：

 
：param path：要包装的文件的路径
：type path：str 
： param field_storage：类：`FileStorage`实例包装
：type field_storage：FileStorage 
：param temporary：当文件实例
被破坏时是否删除文件
：类型临时：bool 
 

你必须真的慢下来，花一点时间才能感觉到的句法混乱。我更喜欢Google的方式（ Google Python样式指南），与上述相似之处像这样：

 
 Args：
 path（str）：要包装的文件的路径
 field_storage（FileStorage ）：FileStorage实例包装
 temporary（bool）：File 
实例被破坏时是否删除文件
 

方式更好！但是，当然，狮身人面像将不会有任何一个，并将所有的文字在Args：之后的一行中展现。

所以总结一下 - 在我去玷污我的代码库与这个reStructuredText语法我想知道是否有任何真正的替代使用它和Sphinx，只是写我自己的API文档。例如，Sphinx是否扩展了处理Google Style Guide的docstring风格？

解决方案

我不认为有比起现在记录python项目的 sphinx 更好。

要更清晰的docstring我最喜欢的选择是使用 sphinx 连同 numpydoc 。根据你的例子，这样看起来像：

  def foo（path，field_storage，temporary）：
这是函数foo 
 
参数
 ---------- 
路径：str 
要包装的文件的路径
 field_storage ：：class：`FileStorage` 
 The：class：`FileStorage`实例包装
 temporary：bool 
当文件实例
被破坏时是否删除文件
 
返回
 ------- 
描述：type 
说明
 ... 
 
示例
 -------- 
这些是用doctest格式写的，应该说明如何
使用这个函数
 
>>> a = [ 1,2,3] 
>>> print [x + 3 for x in a] 
 [4，5，6] 
 ... 
 
 
 pass 
  

（一个完整的例子是这里），
HTML输出将看起来像这个

我认为第一个文件的结构更清晰，更易读。 指南提供了一些更多的信息和约定。 numpydoc 扩展名也适用于 autodoc 。

I'm starting an open source Python project shortly and I'm trying to decide in advance how to write my docstrings. The obvious answer would be using reStructuredText and Sphinx with autodoc, because I really like the idea of simply properly documenting my code in my docstrings then have Sphinx automatically construct an API doc for me.

The problem is the reStructuredText syntax it uses - I think it's completely unreadable before it's rendered. For instance:

: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

You have to really slow down and take a minute to make any sense out of that syntactic jumble. I like much more the Google way (Google Python Style Guide), which counterpart to the above looks like this:

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 nicer! But of course, Sphinx will have none of that and renders all the text after "Args:" in one long line.

So to summarize - before I go and defile my code base with this reStructuredText syntax I would like to know if there are any real alternatives to using it and Sphinx, short of just writing my own API doc. For instance, is there an extension for Sphinx that handles Google Style Guide's docstring style?

解决方案

I don't think that there is something better than sphinx for documenting python projects at the moment.

To have a clearer docstring my favorite choice is using sphinx together with numpydoc. Based on your example this would look like:

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

(a full example is Here), HTML output will look like this

I think the structure of the rst-file is clearer and more readable. The guide gives some more information and conventions. The numpydoc extension works with autodoc as well.

这篇关于对于Python文档，reStructuredText有什么真正的替代方法吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！