什么是标准的Python文档字符串格式?
内容导读
互联网集市收集整理的这篇技术教程文章主要介绍了什么是标准的Python文档字符串格式?,小编现在分享给大家,供广大互联网技能从业者学习和参考。文章包含1907字,纯文字阅读大概需要3分钟。
内容图文
![什么是标准的Python文档字符串格式?](/upload/InfoBanner/zyjiaocheng/716/6bc512caf8e244e78692972e30fd1ec7.jpg)
我在Python中看过几种不同风格的文档字符串,是否有官方或“同意”的风格?
解决方法:
格式
Python文档字符串可以按照其他帖子显示的几种格式编写.但是没有提到默认的Sphinx文档字符串格式,它基于reStructuredText(reST).您可以在that tuto中获得有关主要格式的一些信息.
请注意,PEP 287建议使用reST
接下来是docstrings的主要使用格式.
– Epytext
从历史上看,类似javadoc的风格很普遍,因此它被用作生成文档的Epydoc(使用被称为Epytext格式)的基础.
例:
"""
This is a javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""
– reST
如今,可能更普遍的格式是Sphinx用于生成文档的reStructuredText(reST)格式.
注意:默认情况下,它在JetBrains PyCharm中使用(在定义方法后键入三引号并按Enter键).它也默认用作Pyment中的输出格式.
例:
"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""
– 谷歌
谷歌有自己经常使用的format.它也可以由Sphinx解释(即使用Napoleon plugin).
例:
"""
This is an example of Google style.
Args:
param1: This is the first param.
param2: This is a second param.
Returns:
This is a description of what is returned.
Raises:
KeyError: Raises an exception.
"""
– Numpydoc
请注意,Numpy建议您遵循自己的numpydoc,基于Google格式并可由Sphinx使用.
"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.
Parameters
----------
first : array_like
the 1st param name `first`
second :
the 2nd param
third : {'value', 'other'}, optional
the 3rd param, by default 'value'
Returns
-------
string
a value in a string
Raises
------
KeyError
when a key error
OtherError
when an other error
"""
转换/生成
可以使用像Pyment这样的工具自动生成尚未记录的Python项目的文档字符串,或者将现有文档字符串(可以混合多种格式)从格式转换为另一种格式.
注意:示例来自Pyment documentation
内容总结
以上是互联网集市为您收集整理的什么是标准的Python文档字符串格式?全部内容,希望文章能够帮你解决什么是标准的Python文档字符串格式?所遇到的程序开发问题。 如果觉得互联网集市技术教程内容还不错,欢迎将互联网集市网站推荐给程序员好友。
内容备注
版权声明:本文内容由互联网用户自发贡献,该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容, 请发送邮件至 gblab@vip.qq.com 举报,一经查实,本站将立刻删除。
内容手机端
扫描二维码推送至手机访问。