diff --git a/README.md b/README.md index 1ea931d..99e760c 100644 --- a/README.md +++ b/README.md @@ -18,14 +18,14 @@ Visual Studio Code extension to quickly generate docstrings for python functions ## Docstring Formats -To turn of type generation in docstrings use the `-notypes` template of the desired format. The docBlockr format is a typed version of PEP0257. - -- Google (default) -- docBlockr -- Numpy -- Sphinx -- one-line-sphinx -- PEP0257 +To turn off type generation in docstrings use the `-notypes` template of the desired format. The docBlockr format is a typed version of PEP0257. + +- [google](docs/google.md) +- [sphinx](docs/sphinx.md) +- [numpy](docs/numpy.md) +- [docBlockr](docs/docblockr.md) +- [one-line-sphinx](docs/one-line-sphinx.md) +- [pep257](docs/pep257.md) ## Usage diff --git a/docs/docblockr.md b/docs/docblockr.md new file mode 100644 index 0000000..50ce76e --- /dev/null +++ b/docs/docblockr.md @@ -0,0 +1,27 @@ +# docBlockr Docstring Format + +```python +def abc(a: int, c = [1,2]): + """_summary_ + + Arguments: + a {int} -- _description_ + + Keyword Arguments: + c {list} -- _description_ (default: {[1,2]}) + + Raises: + AssertionError: _description_ + + Returns: + _type_ -- _description_ + """ + if a > 10: + raise AssertionError("a is more than 10") + + return c + if a > 10: + raise AssertionError("a is more than 10") + + return c +``` diff --git a/docs/google.md b/docs/google.md new file mode 100644 index 0000000..90fa1f7 --- /dev/null +++ b/docs/google.md @@ -0,0 +1,21 @@ +# Google Docstring Format + +```python +def abc(a: int, c = [1,2]): + """_summary_ + + Args: + a (int): _description_ + c (list, optional): _description_. Defaults to [1,2]. + + Raises: + AssertionError: _description_ + + Returns: + _type_: _description_ + """ + if a > 10: + raise AssertionError("a is more than 10") + + return c +``` diff --git a/docs/numpy.md b/docs/numpy.md new file mode 100644 index 0000000..4e2f864 --- /dev/null +++ b/docs/numpy.md @@ -0,0 +1,28 @@ +# Numpy Docstring Format + +```python +def abc(a: int, c = [1,2]): + """_summary_ + + Parameters + ---------- + a : int + _description_ + c : list, optional + _description_, by default [1,2] + + Returns + ------- + _type_ + _description_ + + Raises + ------ + AssertionError + _description_ + """ + if a > 10: + raise AssertionError("a is more than 10") + + return c +``` diff --git a/docs/one-line-sphinx.md b/docs/one-line-sphinx.md new file mode 100644 index 0000000..9968c1d --- /dev/null +++ b/docs/one-line-sphinx.md @@ -0,0 +1,16 @@ +# One Line Sphinx Docstring Format + +```python +def abc(a: int, c = [1,2]): + """_summary_ + + :param int a: _description_ + :param list c: _description_, defaults to [1,2] + :raises AssertionError: _description_ + :return _type_: _description_ + """ + if a > 10: + raise AssertionError("a is more than 10") + + return c +``` diff --git a/docs/pep257.md b/docs/pep257.md new file mode 100644 index 0000000..f03f1a5 --- /dev/null +++ b/docs/pep257.md @@ -0,0 +1,23 @@ +# Pep257 Docstring Format + +```python +def abc(a: int, c = [1,2]): + """_summary_ + + Arguments: + a -- _description_ + + Keyword Arguments: + c -- _description_ (default: {[1,2]}) + + Raises: + AssertionError: _description_ + + Returns: + _description_ + """ + if a > 10: + raise AssertionError("a is more than 10") + + return c +``` diff --git a/docs/sphinx.md b/docs/sphinx.md new file mode 100644 index 0000000..d5bee97 --- /dev/null +++ b/docs/sphinx.md @@ -0,0 +1,19 @@ +# Sphinx Docstring Format + +```python +def abc(a: int, c = [1,2]): + """_summary_ + + :param a: _description_ + :type a: int + :param c: _description_, defaults to [1,2] + :type c: list, optional + :raises AssertionError: _description_ + :return: _description_ + :rtype: _type_ + """ + if a > 10: + raise AssertionError("a is more than 10") + + return c +```