Vélin

法语用于Vellum

Vellum是一种准备好的动物皮革或“膜”，通常用作书写材料。羊皮纸是这种材料的另一种说法，如果与羊皮纸区分开来，那么羊皮纸是由小牛皮制成，而不是其他动物的皮，或者质量更高。

安装

根据开发阶段，您可能需要获取numpydoc的修改版本。

$ git clone https://github.com/Carreau/velin
$ cd velin
$ pip install flit
$ flit install --symlink

自动格式化文档字符串

这假定您的文档字符串是RST/Numpydoc格式，并将尝试修复常见的格式错误和打字错误。

velin [--write] <path-to-file.py> or <path-to-dir>

没有--write，vélin将打印建议的diff，带有--write，它将尝试更新文件。

选项

(可能不是最新的，请运行velin --help以检查新、更改或删除的选项)

$ velin --help
usage: velin [-h] [--context context] [--unsafe] [--check] [--no-diff] [--black] [--with-placeholder] [--no-color] [--compact] [--no-fail]
             [--space-in-see-also-title] [--space-in-notes-title] [--no-fixers] [--write]
             path [path ...]

reformat the docstrigns of some file

positional arguments:
  path                  Files or folder to reformat

optional arguments:
  -h, --help            show this help message and exit
  --context context     Number of context lines in the diff
  --unsafe              Lift some safety feature (don't fail if updating the docstring is not indempotent
  --check               Print the list of files/lines number and exit with a non-0 exit status, Use it for CI.
  --no-diff             Do not print the diff
  --black               Do not run black on examples
  --with-placeholder    insert missing sections/parameters placehoders
  --no-color
  --compact             Please ignore
  --no-fail
  --space-in-see-also-title
  --space-in-notes-title
  --no-fixers           try to only reformat and does not run fixers heuristics
  --write               Try to write the updated docstring to the files

--no-fixers

除了重新格式化外，vélin默认会尝试运行一系列启发式方法来更新您的文档字符串

• 删除非现有但已记录的参数，
• 重命名有误的参数，
• 在必要时在冒号前插入空格。

不幸的是，有时这些启发式方法会删除实际内容，例如在以下格式错误的DocString中，返回部分将被删除

def sum(a, b):
    """
    Parameters
    ----------
    a : int
        a number
    b : int
        another number
    Returns
    -------
    s :
        sum of a and b

    See Also
    --------
    substract
    """
    return a + b

由于在返回之前缺少空白行，Numpydoc将解析为5个参数，即a、b、返回、-------和s。由于只有a和b在签名中，它将删除其他参数。

在这种情况下，它将尝试不这样做，因为我们检测到------可能是一个下划线，但还有其他情况下不清楚该怎么做。

因此，您可以通过传递选项--no-fixers来禁用这些修复器

setup.cfg

忽略具有ignore_patterns、filename或filename:qualified_name的文件。您可以在其中放置模式（尝试），但这还不能保证工作。

[velin]
ignore_patterns =
   path/to/a.py:Class.func
   path/to/b.py:Class.func

它修复的类型

• 冒号周围的间距，
• 如果某个参数与函数签名不一致，请进行修正。
• 插入所有缺失的参数，并使用占位符。