# 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 (3.9+) 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.
### Python 2.7
We tried really hard to have this package support both Python 2 and 3 for a
long time. We've dropped Python 2 support officially. Its just become
cumbersome to automate tests for. However, the code will probably still
work in Python 2.7+ *I think*. Good luck!
## 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": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "docstrings, convert-docstrings, formatter",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/5a/b4/c206868c067b704c9cfa7aa52141c41692f741cde9acd4d4d7bcf92ca2dc/docconvert-2.2.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 (3.9+) 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### Python 2.7\n\nWe tried really hard to have this package support both Python 2 and 3 for a\nlong time. We've dropped Python 2 support officially. Its just become\ncumbersome to automate tests for. However, the code will probably still\nwork in Python 2.7+ *I think*. Good luck!\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.2.0",
"project_urls": {
"Changelog": "https://docconvert.readthedocs.io/en/stable/release_notes.html",
"Documentation": "https://docconvert.readthedocs.io/",
"Homepage": "https://github.com/cbillingham/docconvert",
"Issue Tracker": "https://github.com/cbillingham/docconvert/issues"
},
"split_keywords": [
"docstrings",
" convert-docstrings",
" formatter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "85df5620237ef20c9eb5b51aaef1f63f5fa5daf7e25a6a9f17170d287f098f6b",
"md5": "44bfe44f5bc5811c6b7f27424dc5314b",
"sha256": "59ca5bd7e59d830d43cbe9279eb87a048041e9c17a88e12df2516ac6508eee24"
},
"downloads": -1,
"filename": "docconvert-2.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "44bfe44f5bc5811c6b7f27424dc5314b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 34271,
"upload_time": "2024-10-20T23:59:02",
"upload_time_iso_8601": "2024-10-20T23:59:02.509878Z",
"url": "https://files.pythonhosted.org/packages/85/df/5620237ef20c9eb5b51aaef1f63f5fa5daf7e25a6a9f17170d287f098f6b/docconvert-2.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ab4c206868c067b704c9cfa7aa52141c41692f741cde9acd4d4d7bcf92ca2dc",
"md5": "131c26426a7c3f41c4875b7c46a29871",
"sha256": "e3a32e49de2e6a43536e9d2a17d1678c83e83b15126d6f10c097fdf0dfcf6580"
},
"downloads": -1,
"filename": "docconvert-2.2.0.tar.gz",
"has_sig": false,
"md5_digest": "131c26426a7c3f41c4875b7c46a29871",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 28402,
"upload_time": "2024-10-20T23:59:04",
"upload_time_iso_8601": "2024-10-20T23:59:04.296585Z",
"url": "https://files.pythonhosted.org/packages/5a/b4/c206868c067b704c9cfa7aa52141c41692f741cde9acd4d4d7bcf92ca2dc/docconvert-2.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 23:59:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cbillingham",
"github_project": "docconvert",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "docconvert"
}
JSON
