Merge your config files and set parameters from the command line in a simple way.
Project description
Docstripy - Convert any docstring to any format docstring
Transform your python docstrings to the format you want :sparkles:
Support Nympydoc, Google and ReStructuredText as output styles. The input style should be either Numpy, Google, ReST or even a mix of both.
How to use
Install the library via pip:
pip install docstripy
Use it like that to write the files in place. Set a directory path to transform all python files in it.
docstripy <dir-or-file_path> -s=<style> -o=<output_path>
Available styles (style
) are:
- "numpy": Numpy doc style (default)
- "google": Google style
- "rest": ReST style
Cool features
Overwrite the files directly
You can use the -w
(or --overwrite
) option to write the files in place.
docstripy <dir-or-file_path> -s=<style> -w
Notes:
- The module takes into account the fonction definitions. If the definition of the function bring new information, this will be added to the docstring. In case of a conflict, the information in the function definition will be prioritized. It means that docstripy will automatically update your docstring if you update your functions!
- If the old docstring not already contains information on parameters and/or return elements, the output docstring will not specify those elements either. However, if the function definition contains more information, the docstring will be updated with all the corresponding information available in the signature.
For instance:
def my_function(a: int, b: int) -> int:
"""My function
Parameters
----------
a : str
The first argument.
"""
# Here the type of `a` is wrong and the type of `b` is missing.
# Plus, no information is given on the return type.
return a + b
Results in:
def my_function(a: int, b: int) -> int:
"""My function.
Parameters
----------
a : int
The first argument.
b : int
"""
# The type of `a` is fixed, the type of `b` is added.
# No information is given on the return type as it was not present
# in the old docstring.
# Fix some syntax issues (end of line dot and in-between spaces).
return a + b
Max line length
You can control the max line length of the docstring with the --len
option.
By default, there is no limit. The line lenght take into account the indentation
found in the file.
2 spaces indentation
If your files are indented with 2 spaces, you can use the --n_indent=2
option to
the command line.
docstripy <dir-or-file_path> -s=<style> --n_indent=2
Note that the default value is 4 spaces but you can set any value you want.
Create a short docstring when missing
When a function has no docstring, a short one will be created based on the function name. For instance:
def clean_trailing_spaces(line: str) -> new_line: str:
return line.rstrip()
Results in:
def clean_trailing_spaces(line: str) -> new_line: str:
"""Clean trailing spaces."""
return line.rstrip()
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for docstripy-0.4.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 58db219bfdc9b0fd85646512bf91b3a39bdb305cba2eb981e030f28464f61011 |
|
MD5 | 1d497d1b247f5cfca167b0bc5945699f |
|
BLAKE2b-256 | a4296d7efd2ce6d0991934b0887fe6a9f2491959ec77a2fb6563c7917c50fc48 |