对于Python文档来说，除了structuredtext，还有什么其他的选择吗?

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.

我将很快启动一个开源Python项目，并试图提前决定如何编写docstring。最明显的解决方案是使用retrituredtext和autodoc中的Sphinx，因为我非常喜欢在docstring中正确地记录代码，然后让Sphinx自动为我构建一个API doc。

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

问题是它所使用的structuredtext语法——我认为它在呈现之前是完全不可读的。例如:

: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:

你必须放慢语速，花一分钟时间从语法混乱中找到意义。我更喜欢谷歌方式(谷歌Python风格指南)，与上面的类似如下:

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.

更好的方式!当然，狮身人面像将不会有这些，并将所有的文本在“Args:”后的一行中呈现。

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?

总而言之，在我用这种structuredtext语法对代码基进行文件化之前，我想知道除了使用它和Sphinx之外，还有什么其他的替代方法，除了编写我自己的API doc之外。例如，Sphinx是否有一个扩展来处理谷歌样式指南的docstring样式?

7 个解决方案

#1

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

我认为目前还没有比sphinx更好的东西来记录python项目。

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

要有一个更清晰的docstring，我最喜欢的选择是使用sphinx和numpydoc。根据你的例子，这看起来是:

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

(这里有一个完整的示例)，HTML输出将如下所示

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.

我认为列表文件的结构更清晰，可读性更好。指南提供了更多的信息和约定。numpydoc扩展也适用于autodoc。

#2

I have created a Sphinx extension that parses both Google style and NumPy style docstrings, and converts them to standard reStructuredText.

我创建了一个Sphinx扩展，它解析谷歌风格和NumPy样式的docstring，并将它们转换为标准的重构文本。

To use it, simply install it:

要使用它，只需安装它:

$ pip install sphinxcontrib-napoleon

And enable it in conf.py:

并在conf.py中启用:

# conf.py

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

#3

I use epydoc and not sphinx, so this answer may not apply.

我使用的是epydoc，而不是sphinx，所以这个答案可能不适用。

The reStructuredText syntax you describe for documenting methods and functions is not the only possible one. By far, I prefer describing parameters using a consolidated definition list, which is very similar to the Google way:

用于文档化方法和函数的重构文本语法并不是唯一可能的语法。到目前为止，我更喜欢使用统一定义列表来描述参数，这与谷歌方法非常相似:

: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

I would try out if sphix supports it. If it doesn't you may also consider using epydoc just for that (although it is not that actively maintaned right now).

如果sphix支持的话，我就试试。如果没有的话，你也可以考虑仅仅使用epydoc(尽管它现在还没有那么积极地进行维护)。

#4

Actually, reStructuredText as well as the style guide from PEP8 apply mostly for coding the Python's standard library itself, albeit a lot of third party programmers conform to that as well.

实际上，streamlined turedtext以及PEP8中的样式指南主要用于编写Python的标准库本身，尽管许多第三方程序员也遵守这一点。

I agree with you that the Google's style for arguments is much better from an in-code perspective. But you should be able to generate such docstring with sphinx as well, with the new lines and indentation preserved. It doesn't output as nice as with a more sphinxy formatting though.

我同意您的观点，从代码的角度来看，谷歌的参数风格要好得多。但是您也应该能够使用sphinx生成这样的docstring，并保留新的行和缩进。不过，它输出的效果不如更像狮身人面像格式那样好。

Anyway, you don't have to use sphinx, and by the way, the autodoc module of sphinx is definitely just a small part of it. You can virtually use any documentation generator which is capable of retrieving the content of docstrings, like Epydoc (which support epytext as well as reStructuredText, Javadoc or Plaintext) or pydoctor, or even a more universal one like Doxygen.

不管怎样，你不需要使用狮身人面像，顺便说一下，sphinx的autodoc模块只是其中的一小部分。实际上，您可以使用任何能够检索docstring内容的文档生成器，比如Epydoc(它支持epytext，也支持structuredtext, Javadoc或明文)，或者pydoctor，甚至是一个更通用的文档生成器，比如Doxygen。

But definitely, sphinx is quite pythonic, very convenient to use with Python, and make your code consistent with the Python's ecosystem. I think you are not the only one who think this is a "lack". Maybe they will take these complaints into account in the future, or maybe you might even consider modyfying the autodoc module by yourself, should not be very difficult, it's in Python, it would be a good exercise.

但是毫无疑问，sphinx是非常Python化的，使用Python非常方便，并且使您的代码与Python的生态系统一致。我认为你不是唯一一个认为这是“缺乏”的人。也许将来他们会考虑这些抱怨，或者你甚至可以考虑自己对autodoc模块进行建模，应该不是很难，它是在Python中，这是一个很好的练习。

#5

You can write docstrings in any format you like. However, for the sake of every other Python programmer, it's best to use markup and tools that they already know. Their lives is easier if you stick to reST and Sphinx.

您可以以任何您喜欢的格式编写docstring。但是，为了其他Python程序员的利益，最好使用他们已经知道的标记和工具。如果你坚持休息和狮身人面像，他们的生活会更容易。

#6

Python makes the contents of the docstrings available as a __doc__ attribute attached to the function/class/variable object.

Python使docstring的内容作为附加到函数/类/变量对象的__doc__属性可用。

So, you could trivially write a Python program which converts the documentation from whatever format you like into whatever format you like. You could even use Javadoc styling, or XML, or whatever.

因此，您可以编写一个Python程序，它将文档从您喜欢的格式转换为您喜欢的格式。您甚至可以使用Javadoc样式，或XML，或其他任何东西。

Incidentally, since Sphinx is written in Python, making it take non-RST input is just a matter of writing a small amount of Python code.

顺便说一句，由于Sphinx是用Python编写的，因此使用非rst输入只需要编写少量的Python代码。

#7

you just need to start a new line and add a tap after each variable name. Then it is rendered in several lines with consucutive bold variable names:

您只需要启动一个新行，并在每个变量名之后添加一个tap。然后将它呈现在几行中，并使用冒号粗体变量名:

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

#1