# 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 flit
$ flit install --symlink
```
## 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Carreau/minirst",
"name": "velin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Matthias Bussonnier",
"author_email": "bussonniermatthias@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/4b/4d/2932fa9f33801ae5b28c48c7788572b26076f9913450bf4b293e4519f139/velin-0.0.11.tar.gz",
"platform": "",
"description": "# V\u00e9lin\n\nFrench for Vellum\n\n> Vellum is prepared animal skin or \"membrane\", typically used as a material for writing on. Parchment is another term\n> for this material, and if vellum is distinguished from this, it is by vellum being made from calfskin, as opposed to\n> that from other animals,[1] or otherwise being of higher quality\n\n\n## install\n\nYou may need to get a modified version of numpydoc depending on the stage of development.\n\n```\n$ git clone https://github.com/Carreau/velin\n$ cd velin\n$ pip install flit\n$ flit install --symlink\n```\n\n## Autoreformat docstrings\n\nThis assume your docstrings are in RST/Numpydoc format, and will try to fix\ncommon formatting mistakes and typo.\n\n\n```\nvelin [--write] <path-to-file.py> or <path-to-dir>\n```\n\nWithout `--write` v\u00e9lin will print the suggested diff, with `--write` it will _attempt_ to update the files.\n\n## options\n\n(likely not up to date, make sure to run `velin --help` to check for new,changed\nor removed options)\n\n```\n$ velin --help\nusage: velin [-h] [--context context] [--unsafe] [--check] [--no-diff] [--black] [--with-placeholder] [--no-color] [--compact] [--no-fail]\n [--space-in-see-also-title] [--space-in-notes-title] [--no-fixers] [--write]\n path [path ...]\n\nreformat the docstrigns of some file\n\npositional arguments:\n path Files or folder to reformat\n\noptional arguments:\n -h, --help show this help message and exit\n --context context Number of context lines in the diff\n --unsafe Lift some safety feature (don't fail if updating the docstring is not indempotent\n --check Print the list of files/lines number and exit with a non-0 exit status, Use it for CI.\n --no-diff Do not print the diff\n --black Do not run black on examples\n --with-placeholder insert missing sections/parameters placehoders\n --no-color\n --compact Please ignore\n --no-fail\n --space-in-see-also-title\n --space-in-notes-title\n --no-fixers try to only reformat and does not run fixers heuristics\n --write Try to write the updated docstring to the files\n```\n\n## --no-fixers\n\nBeyond reformatting, v\u00e9lin will by default try to run a number of heuristics to update your docstrings:\n\n - Remove non existing but documented parameters,\n - Rename parameter with typos,\n - insert space before colon when necessary.\n\nUnfortunately sometime those heuristics can remove actual content, for example in the malformed DocString below, the\nReturn section would be removed\n\n\n```\ndef sum(a, b):\n \"\"\"\n Parameters\n ----------\n a : int\n a number\n b : int\n another number\n Returns\n -------\n s :\n sum of a and b\n\n See Also\n --------\n substract\n \"\"\"\n return a + b\n\n```\n\nAs there is a missing blank line before return Numpydoc will parse this a 5\nparameters, `a`, `b`, `Returns`, `-------` and `s`. As only `a` and `b` are in\nthe signature, it will remove the other.\n\nWhile in this case it will try not to do that because we detect that `------` is\nlikely an underline, there are other case where it's unclear what to do.\n\nYou can thus disable those fixers by passing the option `--no-fixers`\n\n\n\n\n## setup.cfg\n\n\nIgnore files with ignore_patterns, `filename` or `filename:qualified_name`.\nYou can (try to), put patterns in there, but it's not guarantied to work yet.\n\n```\n[velin]\nignore_patterns =\n path/to/a.py:Class.func\n path/to/b.py:Class.func\n```\n\n## kind of things it fixes\n\n - Spacing around colon,\n - If one parameter has typo wrt function signature: fix it.\n - Insert all missing parameters with placeholders.\n",
"bugtrack_url": null,
"license": "",
"summary": "French for Vellum",
"version": "0.0.11",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ab9559ac2ca3849c4df251053b1e621a8c6c6fb5c786d5b208e81d86ad6f8ba",
"md5": "e0b39b55209c64b204bf29b5febe274a",
"sha256": "d48f1915e31ee18f63c3f053460157e8420ed2f45ff40234a3f36770caf577c6"
},
"downloads": -1,
"filename": "velin-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0b39b55209c64b204bf29b5febe274a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18628,
"upload_time": "2021-04-24T01:34:25",
"upload_time_iso_8601": "2021-04-24T01:34:25.699832Z",
"url": "https://files.pythonhosted.org/packages/0a/b9/559ac2ca3849c4df251053b1e621a8c6c6fb5c786d5b208e81d86ad6f8ba/velin-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4b4d2932fa9f33801ae5b28c48c7788572b26076f9913450bf4b293e4519f139",
"md5": "b476a39a91120c93e7ff7e36c3ef0063",
"sha256": "b0482ba04b9b660e70aa1813c4147319641d663c49749109a74b3e100c64bc8e"
},
"downloads": -1,
"filename": "velin-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "b476a39a91120c93e7ff7e36c3ef0063",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 17984,
"upload_time": "2021-04-24T01:34:27",
"upload_time_iso_8601": "2021-04-24T01:34:27.438728Z",
"url": "https://files.pythonhosted.org/packages/4b/4d/2932fa9f33801ae5b28c48c7788572b26076f9913450bf4b293e4519f139/velin-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-04-24 01:34:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Carreau",
"github_project": "minirst",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "velin"
}
JSON
