# Docconvert
[](https://github.com/cbillingham/docconvert/actions/workflows/test.yaml)
[](https://docconvert.readthedocs.io)
[](https://pypi.org/project/docconvert/)
[](https://pypi.org/project/docconvert/)
[](https://github.com/python/black)
Update or convert docstrings in existing Python files.
This Python (2.7+/3.6+) module and script intends to help Python programmers to
enhance internal code documentation using docstrings.
It is useful 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 modules/functions/methods/classes, it will convert docstrings
with parameters, returns, and other fields formatted in the newly specified style.
Currently, the managed styles in input/output are:
#### Input
- [epytext][1]
- [reST][2] (re-Structured Text, as used by Sphinx)
#### Output
- [google][3]
- [numpy][7]
- [epytext][1]
- [reST][2] (re-Structured Text, as used by Sphinx)
## Getting Started
### Installation
Docconvert can be installed through pip:
```bash
pip install docconvert
```
### Usage
```bash
usage: docconvert [-h] [-i {guess,rest,epytext}] [-o {google,numpy,rest,epytext}]
[--in-place] [-c CONFIG] [-t THREADS] [-v]
source
positional arguments:
source The directory or file to convert.
optional arguments:
-h, --help show this help message and exit
-i {guess,rest,epytext}, --input {guess,rest,epytext}
Input docstring style. (default: guess)
-o {google,numpy,rest,epytext}, --output {google,numpy,rest,epytext}
Output docstring style to convert to. (default: google)
--in-place Write the changes to the input file instead of printing diffs.
-c CONFIG, --config CONFIG
Location of configuration file to use.
-t THREADS, --threads THREADS
Number of threads to use. (default: cpu count)
-v, --verbose Log more information.
```
Examples:
Convert files in `src/mypackage` to google using 4 threads.
```bash
docconvert --output google --threads 4 src/mypackage/
```
Convert file `src/mypackage/myfile.py` from rest to google.
```bash
docconvert --input rest --output google src/mypackage/myfile.py
```
#### Custom Configuration
You can configure optional conversion arguments in a json config file. Just
specify a config filepath to the commandline tool.
```bash
docconvert --config path/to/config.json src/mypackage/
```
Detailed description of all configuration options can be found in the
[documentation][5].
## Contributing
If you would like to contribute, please take a look at the
[contributor documentation][6].
## Versioning
We use [SemVer][4] for versioning.
For the versions available, see the tags on the repository.
## License
This project is licensed under the BSD-3-Clause License.
See the LICENSE.md file for details.
[1]: http://epydoc.sourceforge.net/manual-fields.html
[2]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists
[3]: https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google
[4]: http://semver.org/
[5]: https://docconvert.readthedocs.io/
[6]: https://docconvert.readthedocs.io/en/latest/contributing.html
[7]: https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy
Raw data
{
"_id": null,
"home_page": "https://github.com/cbillingham/docconvert",
"name": "docconvert",
"maintainer": "",
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"maintainer_email": "",
"keywords": "docstrings,convert-docstrings,formatter",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/7b/78/2de34836301b98c2b31d64b1d9e2f7ed184e5683e7a4961a6a0e54fa13b1/docconvert-2.1.0.tar.gz",
"platform": null,
"description": "# Docconvert\n\n[](https://github.com/cbillingham/docconvert/actions/workflows/test.yaml)\n[](https://docconvert.readthedocs.io)\n[](https://pypi.org/project/docconvert/)\n[](https://pypi.org/project/docconvert/)\n[](https://github.com/python/black)\n\nUpdate or convert docstrings in existing Python files.\n\nThis Python (2.7+/3.6+) module and script intends to help Python programmers to\nenhance internal code documentation using docstrings.\nIt is useful 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 modules/functions/methods/classes, it will convert docstrings\nwith parameters, returns, and other fields formatted in the newly specified style.\n\nCurrently, the managed styles in input/output are:\n\n#### Input\n\n- [epytext][1]\n- [reST][2] (re-Structured Text, as used by Sphinx)\n\n#### Output\n\n- [google][3]\n- [numpy][7]\n- [epytext][1]\n- [reST][2] (re-Structured Text, as used by Sphinx)\n\n\n## Getting Started\n\n### Installation\n\nDocconvert can be installed through pip:\n\n```bash\npip install docconvert\n```\n\n### Usage\n\n```bash\nusage: docconvert [-h] [-i {guess,rest,epytext}] [-o {google,numpy,rest,epytext}]\n [--in-place] [-c CONFIG] [-t THREADS] [-v]\n source\n\npositional arguments:\n source The directory or file to convert.\n\noptional arguments:\n -h, --help show this help message and exit\n -i {guess,rest,epytext}, --input {guess,rest,epytext}\n Input docstring style. (default: guess)\n -o {google,numpy,rest,epytext}, --output {google,numpy,rest,epytext}\n Output docstring style to convert to. (default: google)\n --in-place Write the changes to the input file instead of printing diffs.\n -c CONFIG, --config CONFIG\n Location of configuration file to use.\n -t THREADS, --threads THREADS\n Number of threads to use. (default: cpu count)\n -v, --verbose Log more information.\n```\n\nExamples:\n\nConvert files in `src/mypackage` to google using 4 threads.\n\n```bash\ndocconvert --output google --threads 4 src/mypackage/\n```\n\nConvert file `src/mypackage/myfile.py` from rest to google.\n\n```bash\ndocconvert --input rest --output google src/mypackage/myfile.py\n```\n\n#### Custom Configuration\n\nYou can configure optional conversion arguments in a json config file. Just\nspecify a config filepath to the commandline tool.\n\n```bash\ndocconvert --config path/to/config.json src/mypackage/\n```\n\nDetailed description of all configuration options can be found in the\n[documentation][5].\n\n\n## Contributing\n\nIf you would like to contribute, please take a look at the\n[contributor documentation][6].\n\n\n## Versioning\n\nWe use [SemVer][4] for versioning.\nFor the versions available, see the tags on the repository.\n\n\n## License\n\nThis project is licensed under the BSD-3-Clause License.\nSee the LICENSE.md file for details.\n\n\n[1]: http://epydoc.sourceforge.net/manual-fields.html\n[2]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#info-field-lists\n[3]: https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google\n[4]: http://semver.org/\n[5]: https://docconvert.readthedocs.io/\n[6]: https://docconvert.readthedocs.io/en/latest/contributing.html\n[7]: https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Convert and conform package docstrings to a new style",
"version": "2.1.0",
"split_keywords": [
"docstrings",
"convert-docstrings",
"formatter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8fc0b367b5a21833398f01a617ab082102b4b1e81036b8fb1e27bb43f6192e7a",
"md5": "d324232467fda47796b8eb6908ee1cbd",
"sha256": "5ee1a6e046fa66b45c71f291169b668e5d9d8ecb11048b2d7dc8da89f3743a71"
},
"downloads": -1,
"filename": "docconvert-2.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d324232467fda47796b8eb6908ee1cbd",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"size": 32926,
"upload_time": "2023-01-31T05:35:12",
"upload_time_iso_8601": "2023-01-31T05:35:12.753583Z",
"url": "https://files.pythonhosted.org/packages/8f/c0/b367b5a21833398f01a617ab082102b4b1e81036b8fb1e27bb43f6192e7a/docconvert-2.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7b782de34836301b98c2b31d64b1d9e2f7ed184e5683e7a4961a6a0e54fa13b1",
"md5": "4c4644c316165bf67eb47cab98edbb80",
"sha256": "87daee964d32770b3cbae3c68f923a397f58ef85b39223cd712d83ef244f7ba4"
},
"downloads": -1,
"filename": "docconvert-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "4c4644c316165bf67eb47cab98edbb80",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"size": 27004,
"upload_time": "2023-01-31T05:35:14",
"upload_time_iso_8601": "2023-01-31T05:35:14.895127Z",
"url": "https://files.pythonhosted.org/packages/7b/78/2de34836301b98c2b31d64b1d9e2f7ed184e5683e7a4961a6a0e54fa13b1/docconvert-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 05:35:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "cbillingham",
"github_project": "docconvert",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "docconvert"
}
JSON
