Vélin
French for Vellum
Vellum is prepared animal skin or "membrane", typically used as a material for writing on. Parchment is another term for this material, and if vellum is distinguished from this, it is by vellum being made from calfskin, as opposed to that from other animals,[1] or otherwise being of higher quality
install
You may need to get a modified version of numpydoc depending on the stage of development.
$ git clone https://github.com/Carreau/velin
$ cd velin
$ pip install -e .
(You will need a quite recent pip and flit to do so)
Autoreformat docstrings
This assume your docstrings are in RST/Numpydoc format, and will try to fix common formatting mistakes and typo.
velin [--write] <path-to-file.py> or <path-to-dir>
Without --write vélin will print the suggested diff, with --write it will attempt to update the files.
options
(likely not up to date, make sure to run velin --help to check for new,changed
or removed options)
$ 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
Beyond reformatting, vélin will by default try to run a number of heuristics to update your docstrings:
- Remove non existing but documented parameters,
- Rename parameter with typos,
- insert space before colon when necessary.
Unfortunately sometime those heuristics can remove actual content, for example in the malformed DocString below, the Return section would be removed
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
As there is a missing blank line before return Numpydoc will parse this a 5
parameters, a, b, Returns, ------- and s. As only a and b are in
the signature, it will remove the other.
While in this case it will try not to do that because we detect that ------ is
likely an underline, there are other case where it's unclear what to do.
You can thus disable those fixers by passing the option --no-fixers
setup.cfg
Ignore files with ignore_patterns, filename or filename:qualified_name.
You can (try to), put patterns in there, but it's not guarantied to work yet.
[velin]
ignore_patterns =
path/to/a.py:Class.func
path/to/b.py:Class.func
kind of things it fixes
- Spacing around colon,
- If one parameter has typo wrt function signature: fix it.
- Insert all missing parameters with placeholders.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent