斯芬克斯“拿破仑”扩建。
sphinxcontrib-napoleon的Python项目详细描述
注意
从狮身人面像1.3开始，拿破仑分机将与
狮身人面像在sphinx.ext.napoleon下面。扩展名sphinxcontrib.napoleon
将继续使用sphinx<；=1.2。
您厌倦了编写这样的docstring吗：
: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 :returns: A buffered writable file descriptor :rtype: BufferedFileStorage
ReStructuredText很好，但它创建了视觉密集、难以阅读的 docstrings。把上面的混乱和重写的一样东西比较一下 根据Google Python Style Guide：
Args:
path (str): The path of the file to wrap
field_storage (FileStorage): The :class:`FileStorage` instance to wrap
temporary (bool): Whether or not to delete the file when the File
instance is destructed
Returns:
BufferedFileStorage: A buffered writable file descriptor
更清晰，不是吗？
拿破仑是一个Sphinx extension使狮身人面像能够同时解析这两个NumPy 以及Google样式的docstrings-由Khan Academy推荐的样式。
napoleon是一个预处理器，它解析NumPy和Google样式 在Sphinx尝试 分析它们。这发生在斯芬克斯正在处理的中间步骤中 文档，因此它不会修改实际 源代码文件。
开始
安装拿破仑加长件：
$ pip install sphinxcontrib-napoleon
在setting up Sphinx构建文档之后，在 斯芬克斯
conf.py文件：# conf.py # Add napoleon to the extensions list extensions = ['sphinxcontrib.napoleon']
使用
sphinx-apidoc构建您的api文档：$ sphinx-apidoc -f -o docs/source projectdir
文档字符串
拿破仑解释了Sphinx autodoc能找到的每个文档字符串， 包括文档字符串：modules，classes，attributes， methods、functions和variables。在每个docstring中， 特殊格式的Sections被解析并转换为 重组文本。
所有标准的structuredText格式仍按预期工作。
文档字符串节
支持以下所有节标题：
- ^{tt7}$ (alias of Parameters)
- ^{tt8}$ (alias of Parameters)
- ^{tt9}$
- ^{tt10}$
- ^{tt11}$
- ^{tt12}$ (alias of Keyword Arguments)
- ^{tt13}$
- ^{tt14}$
- ^{tt15}$
- ^{tt16}$
- ^{tt17}$
- ^{tt18}$
- ^{tt19}$ (alias of Returns)
- ^{tt20}$
- ^{tt21}$
- ^{tt22}$
- ^{tt23}$
- ^{tt24}$
- ^{tt25}$ (alias of Warning)
- ^{tt26}$
- ^{tt27}$ (alias of Yields)
- ^{tt28}$
谷歌vs Numpy
napoleon支持两种类型的docstring：Google和NumPy。这个 这两种风格的主要区别在于google使用缩进 单独的部分，而numpy使用下划线。
谷歌风格：
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True
纽米风格：
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
"""
return True
numpy风格倾向于需要更多的垂直空间，而google风格 倾向于使用更多的水平空间。谷歌风格往往更容易 阅读简短的文档字符串，而numpy风格更容易 阅读长而深入的文档字符串。
Khan Academy建议使用google风格。
在风格之间的选择很大程度上是审美的，但这两种风格应该 不要混为一谈。为你的项目选择一种风格并与之保持一致。
欢迎加入QQ群-->： 979659372
