pyment
======
Create, update or convert docstrings in existing Python files, managing several styles.
.. contents:: :local:
Description
-----------
This Python (2.7+/3+, or 2.6 if installed _argparser_) program intends to help Python programmers to enhance inside code documentation using docstrings.
It is useful for code not well documented, or code without docstrings, or some not yet or partially documented code, or a mix of all of this :-)
It can be helpful also to harmonize or change a project docstring style format.
It will parse one or several python scripts and retrieve existing docstrings.
Then, for all found functions/methods/classes, it will generate formatted docstrings with parameters, default values,...
At the end, patches are generated for each file. Then, man can apply the patches to the initial scripts.
An option allow to update the files directly without generating patches.
It is also possible to generate the python file with the new docstrings, or to retrieve only the docstrings...
Currently, the managed styles in input/output are javadoc, one variant of reST (re-Structured Text, used by Sphinx), numpydoc, google docstrings, groups (other grouped style).
You can also configure some settings via the command line or a configuration
file.
To get further information please refer to the `documentation <https://github.com/dadadel/pyment/blob/master/doc/sphinx/source/pyment.rst>`_.
The tool, at the time, offer to generate patches or get a list of the new docstrings (created or converted).
You can contact the developer *dadel* and speak about the project on **IRC** **Freenode**'s channel **#pyment**.
Start quickly
-------------
- get and install:
.. code-block:: sh
$ git install pyment
or
$ pip install git+https://github.com/dadadel/pyment.git
- run from the command line:
.. code-block:: sh
$ pyment myfile.py # will generate a patch
$ pyment -w myfile.py # will overwrite the file
or
.. code-block:: sh
$ pyment my/folder/
- get help:
.. code-block:: sh
$ pyment -h
- run from a script:
.. code-block:: python
import os
from pyment import PyComment
filename = 'test.py'
c = PyComment(filename)
c.proceed()
c.diff_to_file(os.path.basename(filename) + ".patch")
for s in c.get_output_docs():
print(s)
Example
-------
Here is a full example using Pyment to generate a patch and then apply the patch.
Let's consider a file *test.py* with following content:
.. code-block:: python
def func(param1=True, param2='default val'):
'''Description of func with docstring groups style.
Params:
param1 - descr of param1 that has True for default value.
param2 - descr of param2
Returns:
some value
Raises:
keyError: raises key exception
TypeError: raises type exception
'''
pass
class A:
def method(self, param1, param2=None):
pass
Now let's use Pyment:
.. code-block:: sh
$ pyment test.py
Using Pyment without any argument will autodetect the docstrings formats and generate a patch using the reStructured Text format.
So the previous command has generated the file *test.py.patch* with following content:
.. code-block:: patch
# Patch generated by Pyment v0.2.0
--- a/test.py
+++ b/test.py
@@ -1,20 +1,22 @@
def func(param1=True, param2='default val'):
- '''Description of func with docstring groups style.
+ """Description of func with docstring groups style.
- Params:
- param1 - descr of param1 that has True for default value.
- param2 - descr of param2
+ :param param1: descr of param1 that has True for default value
+ :param param2: descr of param2 (Default value = 'default val')
+ :returns: some value
+ :raises keyError: raises key exception
+ :raises TypeError: raises type exception
- Returns:
- some value
-
- Raises:
- keyError: raises key exception
- TypeError: raises type exception
-
- '''
+ """
pass
class A:
+ """ """
def method(self, param1, param2=None):
+ """
+
+ :param param1:
+ :param param2: (Default value = None)
+
+ """
pass
Let's finally apply the patch with the following command:
.. code-block:: sh
$ patch -p1 < test.py.patch
Now the original *test.py* was updated and its content is now:
.. code-block:: python
def func(param1=True, param2='default val'):
"""Description of func with docstring groups style.
:param param1: descr of param1 that has True for default value
:param param2: descr of param2 (Default value = 'default val')
:returns: some value
:raises keyError: raises key exception
:raises TypeError: raises type exception
"""
pass
class A:
""" """
def method(self, param1, param2=None):
"""
:param param1:
:param param2: (Default value = None)
"""
pass
Also refer to the files `example.py.patch <https://github.com/dadadel/pyment/blob/master/example.py.patch>`_ or `example_numpy.py.patch <https://github.com/dadadel/pyment/blob/master/example_numpy.py.patch>`_ to see some other results that can be obtained processing the file `example.py <https://github.com/dadadel/pyment/blob/master/example.py>`_
Offer a coffee or a beer
------------------------
If you enjoyed this free software, and want to thank me, you can offer me some
bitcoins for a coffee, a beer, or more, I would be happy :)
Here's my address for bitcoins : 1Kz5bu4HuRtwbjzopN6xWSVsmtTDK6Kb89
Raw data
{
"_id": null,
"home_page": "https://github.com/dadadel/pyment",
"name": "pyment",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "pyment docstring numpydoc googledoc restructuredtext epydoc epytext javadoc development generate auto",
"author": "A. Daouzli",
"author_email": "dadel@hadoly.fr",
"download_url": "https://files.pythonhosted.org/packages/dd/9e/c58a151c7020f6fdd48eea0085a9d1c91a57da19fa4e7bff0daf930c9900/Pyment-0.3.3.tar.gz",
"platform": "any",
"description": "pyment\n======\n\nCreate, update or convert docstrings in existing Python files, managing several styles.\n\n.. contents:: :local:\n\nDescription\n-----------\n\nThis Python (2.7+/3+, or 2.6 if installed _argparser_) program intends to help Python programmers to enhance inside code documentation using docstrings.\nIt is useful for code not well documented, or code without docstrings, or some not yet or partially documented code, or a mix of all of this :-)\nIt can be helpful also to harmonize or change a project docstring style format.\n\nIt will parse one or several python scripts and retrieve existing docstrings.\nThen, for all found functions/methods/classes, it will generate formatted docstrings with parameters, default values,...\n\nAt the end, patches are generated for each file. Then, man can apply the patches to the initial scripts.\nAn option allow to update the files directly without generating patches.\nIt is also possible to generate the python file with the new docstrings, or to retrieve only the docstrings...\n\nCurrently, the managed styles in input/output are javadoc, one variant of reST (re-Structured Text, used by Sphinx), numpydoc, google docstrings, groups (other grouped style).\n\nYou can also configure some settings via the command line or a configuration\nfile.\n\nTo get further information please refer to the `documentation <https://github.com/dadadel/pyment/blob/master/doc/sphinx/source/pyment.rst>`_.\n\nThe tool, at the time, offer to generate patches or get a list of the new docstrings (created or converted).\n\nYou can contact the developer *dadel* and speak about the project on **IRC** **Freenode**'s channel **#pyment**.\n\nStart quickly\n-------------\n- get and install:\n\n.. code-block:: sh\n\n $ git install pyment\n or\n $ pip install git+https://github.com/dadadel/pyment.git\n\n- run from the command line:\n\n.. code-block:: sh\n\n $ pyment myfile.py # will generate a patch\n $ pyment -w myfile.py # will overwrite the file\n\nor\n\n.. code-block:: sh\n\n $ pyment my/folder/\n\n- get help:\n\n.. code-block:: sh\n\n $ pyment -h\n\n- run from a script:\n\n.. code-block:: python\n\n import os\n from pyment import PyComment\n\n filename = 'test.py'\n\n c = PyComment(filename)\n c.proceed()\n c.diff_to_file(os.path.basename(filename) + \".patch\")\n for s in c.get_output_docs():\n print(s)\n\nExample\n-------\n\nHere is a full example using Pyment to generate a patch and then apply the patch.\n\nLet's consider a file *test.py* with following content:\n\n.. code-block:: python\n\n def func(param1=True, param2='default val'):\n '''Description of func with docstring groups style.\n\n Params:\n param1 - descr of param1 that has True for default value.\n param2 - descr of param2\n\n Returns:\n some value\n\n Raises:\n keyError: raises key exception\n TypeError: raises type exception\n\n '''\n pass\n\n class A:\n def method(self, param1, param2=None):\n pass\n\nNow let's use Pyment:\n\n.. code-block:: sh\n\n $ pyment test.py\n\nUsing Pyment without any argument will autodetect the docstrings formats and generate a patch using the reStructured Text format.\nSo the previous command has generated the file *test.py.patch* with following content:\n\n.. code-block:: patch\n\n # Patch generated by Pyment v0.2.0\n\n --- a/test.py\n +++ b/test.py\n @@ -1,20 +1,22 @@\n def func(param1=True, param2='default val'):\n - '''Description of func with docstring groups style.\n + \"\"\"Description of func with docstring groups style.\n\n - Params: \n - param1 - descr of param1 that has True for default value.\n - param2 - descr of param2\n + :param param1: descr of param1 that has True for default value\n + :param param2: descr of param2 (Default value = 'default val')\n + :returns: some value\n + :raises keyError: raises key exception\n + :raises TypeError: raises type exception\n\n - Returns:\n - some value\n -\n - Raises:\n - keyError: raises key exception\n - TypeError: raises type exception\n -\n - '''\n + \"\"\"\n pass\n\n class A:\n + \"\"\" \"\"\"\n def method(self, param1, param2=None):\n + \"\"\"\n +\n + :param param1: \n + :param param2: (Default value = None)\n +\n + \"\"\"\n pass\n\nLet's finally apply the patch with the following command:\n\n.. code-block:: sh\n\n $ patch -p1 < test.py.patch\n\nNow the original *test.py* was updated and its content is now:\n\n.. code-block:: python\n\n def func(param1=True, param2='default val'):\n \"\"\"Description of func with docstring groups style.\n\n :param param1: descr of param1 that has True for default value\n :param param2: descr of param2 (Default value = 'default val')\n :returns: some value\n :raises keyError: raises key exception\n :raises TypeError: raises type exception\n\n \"\"\"\n pass\n\n class A:\n \"\"\" \"\"\"\n def method(self, param1, param2=None):\n \"\"\"\n\n :param param1: \n :param param2: (Default value = None)\n\n \"\"\"\n pass\n\nAlso refer to the files `example.py.patch <https://github.com/dadadel/pyment/blob/master/example.py.patch>`_ or `example_numpy.py.patch <https://github.com/dadadel/pyment/blob/master/example_numpy.py.patch>`_ to see some other results that can be obtained processing the file `example.py <https://github.com/dadadel/pyment/blob/master/example.py>`_ \n\n\nOffer a coffee or a beer\n------------------------\n\nIf you enjoyed this free software, and want to thank me, you can offer me some\nbitcoins for a coffee, a beer, or more, I would be happy :)\n\nHere's my address for bitcoins : 1Kz5bu4HuRtwbjzopN6xWSVsmtTDK6Kb89\n\n\n\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "Generate/convert automatically the docstrings from code signature",
"version": "0.3.3",
"split_keywords": [
"pyment",
"docstring",
"numpydoc",
"googledoc",
"restructuredtext",
"epydoc",
"epytext",
"javadoc",
"development",
"generate",
"auto"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "4e4e92c112068fcaff6d07779b51d5a6",
"sha256": "a0c6ec59d06d24aeec3eaecb22115d0dc95d09e14209b2df838381fdf47a78cc"
},
"downloads": -1,
"filename": "Pyment-0.3.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e4e92c112068fcaff6d07779b51d5a6",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 21924,
"upload_time": "2018-07-29T19:20:51",
"upload_time_iso_8601": "2018-07-29T19:20:51.082638Z",
"url": "https://files.pythonhosted.org/packages/52/01/810e174c28a7dcf5f91c048faf69c84eafee60c9a844e4ce21671b2e99bb/Pyment-0.3.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "08b6a412cb423b1dd8cec043bc71f3a1",
"sha256": "951a4c52d6791ccec55bc739811169eed69917d3874f5fe722866623a697f39d"
},
"downloads": -1,
"filename": "Pyment-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "08b6a412cb423b1dd8cec043bc71f3a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 21003,
"upload_time": "2018-07-29T19:20:52",
"upload_time_iso_8601": "2018-07-29T19:20:52.601222Z",
"url": "https://files.pythonhosted.org/packages/dd/9e/c58a151c7020f6fdd48eea0085a9d1c91a57da19fa4e7bff0daf930c9900/Pyment-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2018-07-29 19:20:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dadadel",
"github_project": "pyment",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"appveyor": true,
"lcname": "pyment"
}
JSON
