有没有真正的替代Python文档的reStructuredText?

我很快就开始了一个开源的Python项目,并且正在尝试提前决定如何编写我的文档。 显而易见的答案是将reStructuredText和Sphinx与autodoc结合使用,因为我非常喜欢简单地在我的文档中恰当地logging我的代码的想法,然后让Sphinx自动为我构build一个API文档。

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

 :param path:要包装的文件的path
 :inputpath:str
 :param field_storage:要包装的:class:`FileStorage`实例
 :inputfield_storage:FileStorage
 :param temporary:是否在File实例中删除文件
    被破坏
 :inputtemporary:bool

你必须真的放慢速度,花一点时间去理解这种句法混乱。 我更喜欢谷歌的方式( 谷歌Python风格指南 ),与上述相对应的是这样的:

 ARGS:
    path(str):要包装的文件的path
     field_storage(FileStorage):要包装的FileStorage实例
    临时(bool):文件是否删除时的文件
        实例被破坏

更好! 但是,当然,狮身人面像将不会有这样的东西,并且在“长矛”之后把所有的文字都排成一列。

所以总结一下 – 在我用这个reStructuredText语法去玷污我的代码库之前,我想知道是否有任何真正的替代方法来使用它和Sphinx,而不仅仅是编写我自己的API文档。 例如,是否有一个处理Google Style Guide文档string样式的Sphinx扩展?

我不认为有什么比sphinx文件目前的Python项目更好。

要有一个更清晰的文档string,我最喜欢的select是与numpydoc一起使用sphinx 。 根据你的例子,这看起来像:

 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 

(一个完整的例子就是这里 ),HTML输出将如下所示

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

我创build了一个Sphinx扩展 ,用于parsingGoogle样式和NumPy样式文档,并将其转换为标准reStructuredText。

要使用它,只需安装它:

 $ pip install sphinxcontrib-napoleon 

并在conf.py中启用它:

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

拿破仑的更多文档在这里 。

我使用epydoc而不是狮身人面像,所以这个答案可能不适用。

您描述的logging方法和函数的reStructuredText语法不是唯一可能的。 到目前为止,我更喜欢用统一的定义列表来描述参数,这与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 

我会尝试,如果sphix支持它。 如果没有,你也可以考虑使用epydoc(虽然现在还没有被积极维护)。

实际上, reStructuredText以及PEP8的风格指南主要适用于Python标准库自身的编码,尽pipe很多第三方程序员也一样。

我同意你的观点,从代码的angular度来看,Google对于论点的风格要好得多。 但是你也应该能够用狮身人面像来生成这样的文档string, 并保留新的行和缩进 。 它不会像使用更多的sphinxy格式那样输出。

无论如何,你不必使用狮身人面像,顺便说一句,狮身人面像的autodoc模块绝对只是它的一小部分。 您几乎可以使用任何能够检索docstrings内容的文档生成器,如Epydoc (支持epytext以及reStructuredText,Javadoc或Plaintext )或pydoctor ,或者甚至是像Doxygen这样更通用的文档生成器。

但是,sphinx绝对是pythonic ,使用Python非常方便,并使您的代码与Python生态系统保持一致。 我认为你不是唯一认为这是“缺乏”的人。 也许他们将来会把这些抱怨考虑进去,或者你甚至可能会考虑自己来autodoc模块,不应该很困难,这是Python中的,这将是一个很好的练习。

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

Python将docstrings的内容作为附加到函数/类/variables对象的__doc__属性提供。

所以,你可以简单地编写一个Python程序,把你喜欢的任何格式的文档转换成你喜欢的任何格式。 你甚至可以使用Javadoc样式,或XML,或其他。

顺便说一句,因为Sphinx是用Python编写的,所以使用非RSTinput只是编写less量的Python代码。

你只需要开始一个新的行,并添加每个variables名后面的水龙头。 然后用几行粗体variables名称来呈现它们:

 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