文档
开发 Python 包
James Fulton
Climate informatics researcher
为何编写文档？
- 帮助用户使用您的代码
- 逐一文档化
- 函数
- 类
- 类方法
import numpy as np
help(np.sum)
...
sum(a, axis=None, dtype=None, out=None)
Sum of array elements over a given axis.
Parameters
----------
a : array_like
Elements to sum.
axis : None or int or tuple of ints, optional
Axis or axes along which a sum is performed.
The default, axis=None, will sum all of the
elements of the input array.
...
为何编写文档？
- 帮助用户使用您的代码
- 逐一文档化
- 函数
- 类
- 类方法
import numpy as np
help(np.array)
...
array(object, dtype=None, copy=True)
Create an array.
Parameters
----------
object : array_like
An array, any object exposing the array
interface ...
dtype : data-type, optional
The desired data-type for the array.
copy : bool, optional
If true (default), then the object is copied.
...
为何编写文档？
- 帮助用户使用您的代码
- 逐一文档化
- 函数
- 类
- 类方法
import numpy as np
x = np.array([1,2,3,4])
help(x.mean)
...
mean(...) method of numpy.ndarray instance
a.mean(axis=None, dtype=None, out=None)
Returns the average of the array elements
along given axis.
Refer to `numpy.mean` for full documentation.
...
函数文档
def count_words(filepath, words_list):""" ... """
函数文档
def count_words(filepath, words_list):"""统计这些词出现的总次数。"""
函数文档
def count_words(filepath, words_list):"""统计这些词出现的总次数。 在给定位置的文本文件上进行计数。 """
函数文档
def count_words(filepath, words_list):"""统计这些词出现的总次数。 在给定位置的文本文件上进行计数。 [解释 filepath 和 words_list 是什么] [返回值是什么] """
文档风格
Google 文档风格
"""摘要行。
函数的扩展说明。
Args:
arg1 (int): arg1 的说明
arg2 (str): arg2 的说明
NumPy 风格
"""摘要行。
函数的扩展说明。
Parameters
----------
arg1 : int
arg1 的说明...
Returns
----------
numpy.ndarray
reStructuredText 风格
"""摘要行。
函数的扩展说明。
:param arg1: arg1 的说明
:type arg1: int
:param arg2: arg2 的说明
:type arg2: str
Epytext 风格
"""摘要行。
函数的扩展说明。
@type arg1: int
@param arg1: arg1 的说明
@type arg2: str
@param arg2: arg2 的说明
NumPy 文档风格
在科学 Python 包中很常见，如：
numpyscipypandassklearnmatplotlibdask- 等等
NumPy 文档风格
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear') Compute the q-th percentile of the data along the specified axis. Returns the q-th percentile(s) of the array elements.Parameters ----------a : array_likeInput array or object that can be converted to an array.
其他类型包括 - int、float、bool、str、dict、numpy.array 等
NumPy 文档风格
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
...
Parameters
----------
...
axis : {int, tuple of int, None}
...
interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
- 如合适，为参数列出多种类型
- 若仅少数有效选项，列出可接受值
NumPy 文档风格
import scipy
help(scipy.percentile)
percentile(a, q, axis=None, out=None, overwrite_input=False, interpolation='linear')
...
Returns
-------
percentile : scalar or ndarray
If `q` is a single percentile and `axis=None`, then the result
is a scalar. If multiple percentiles are given, first axis of
the result corresponds to the percentiles...
...
NumPy 文档风格
其他章节
RaisesSee AlsoNotesReferencesExamples
1 https://numpydoc.readthedocs.io/en/latest/format.html
文档模板与风格转换
- 可用
pyment生成文档字符串 - 从终端运行
- 支持以下文档风格
- Numpydoc
- reST（即 reStructuredText）
- Javadoc（即 epytext）
- 可在风格之间转换
文档模板与风格转换
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
# 打开文本文件
...
return n
-w- 覆盖文件-o numpydoc- 以 NumPy 风格输出
文档模板与风格转换
pyment -w -o numpydoc textanalysis.py
def count_words(filepath, words_list):
"""
Parameters
----------
filepath :
words_list :
Returns
-------
type
"""
转换为 Google 风格
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""统计这些词出现的总次数。
在给定位置的文本文件上进行计数。
Parameters
----------
filepath : str
文本文件路径。
words_list : list of str
统计这些词的出现总次数。
Returns
-------
"""
转换为 Google 风格
pyment -w -o google textanalysis.py
def count_words(filepath, words_list):
"""统计这些词出现的总次数。
在给定位置的文本文件上进行计数。
Args:
filepath(str): 文本文件路径。
words_list(list of str): 统计这些词的出现总次数。
Returns:
"""
包、子包与模块文档
mysklearn/__init__.py
"""
Python 的线性回归
============================
mysklearn 是一个用于在 Python 中实现
线性回归的完整包。
"""
mysklearn/preprocessing/__init__.py
"""
用于标准预处理操作的子包。
"""
mysklearn/preprocessing/normalize.py
"""
用于数据标准化的模块。
"""
Passons à la pratique !
开发 Python 包
