docstrfmt: a formatter for Sphinx flavored reStructuredText
===========================================================
.. image:: https://img.shields.io/pypi/v/docstrfmt.svg
:alt: Latest docstrfmt Version
:target: https://pypi.python.org/pypi/docstrfmt
.. image:: https://img.shields.io/pypi/pyversions/docstrfmt
:alt: Supported Python Versions
:target: https://pypi.python.org/pypi/docstrfmt
.. image:: https://img.shields.io/pypi/dm/docstrfmt
:alt: PyPI - Downloads - Monthly
:target: https://pypi.python.org/pypi/docstrfmt
.. image:: https://coveralls.io/repos/github/LilSpazJoekp/docstrfmt/badge.svg?branch=master
:alt: Coveralls Coverage
:target: https://coveralls.io/github/LilSpazJoekp/docstrfmt?branch=master
.. image:: https://github.com/LilSpazJoekp/docstrfmt/workflows/CI/badge.svg
:alt: Github Actions Coverage
:target: https://github.com/LilSpazJoekp/docstrfmt/actions?query=branch%3Amaster
.. image:: https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg
:alt: Contributor Covenant
:target: https://github.com/ilSpazJoekp/docstrfmt/blob/master/CODE_OF_CONDUCT.md
*Strongly inspired by* rstfmt_ and rustfmt_.
*This is considered to be in beta however it is mostly stable.*
Description
-----------
docstrfmt is a tool for automatically formatting reStructuredText_ in files and Python
docstrings in a consistent way.
Like Black_ and rstfmt_, the motivation is to provide a format that is reasonable and
minimally configurable to prevent teams from wasting time on style discussions (or
individuals on manually doing formatting, for that matter).
Currently, docstrfmt is in an early stage of development. The most common reST
constructs are covered but there are some that are not. If there is a construct missing
and would like to add it, feel free to open a PR to add it or open an issue and I'll see
what I can do.
To get a feel for the output of docstrfmt, see `the sample file <sample.rst>`__.
Differences between docstrfmt and rstfmt_
-----------------------------------------
The main difference between rstfmt_ and docstrfmt is the ability to format Python
docstrings. I am open to merging this project with rstfmt_, however, there as several
differences in formatting conventions between the two (hence the separate fork).
Usage
-----
.. code-block:: sh
# Install.
pip install docstrfmt
# Install the development version.
pip install https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip
# Read a file from stdin and write the formatted version to stdout.
docstrfmt
# Format the given file(s) in place.
docstrfmt <file>...
# Format the given files, printing all output to stdout.
docstrfmt -o <file>...
# Wrap paragraphs to the given line length where possible (default 88).
docstrfmt -l <length>
Like Black's blackd_, there is also a daemon that provides formatting via HTTP requests
to avoid the cost of starting and importing everything on every run.
.. code-block:: sh
# Install.
pip install "docstrfmt[d]"
# Install the development version.
pip install "https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip#egg=docstrfmt[d]"
# Start the daemon (binds to localhost:5219 by default).
docstrfmtd --bind-host=<host> --bind-port=<port>
# Print the formatted version of a file.
curl http://locahost:5219 --data-binary @<file>
# Specify the line length (default 88).
curl -H 'X-Line-Length: 72' http://locahost:5219 --data-binary @<file>
# Mimic the standalone tool: read from stdin, write to stdout, exit with
# a nonzero status code if there are errors.
curl -fsS http://locahost:5219 --data-binary @/dev/stdin
With editors
~~~~~~~~~~~~
PyCharm
+++++++
Instructions derived from `black documentation
<https://black.readthedocs.io/en/stable/editor_integration.html#pycharm-intellij-idea>`_
1. Install.
.. code-block:: sh
pip install "docstrfmt[d]"
2. Locate where `docstrfmt` is installed.
- On macOS / Linux / BSD:
.. code-block:: sh
which docstrfmt
# /usr/local/bin/docstrfmt # possible location
- On Windows:
.. code-block:: shell
where docstrfmt
# C:\Program Files\Python39\Scripts\docstrfmt.exe
.. note::
Note that if you are using a virtual environment detected by PyCharm, this is an
unneeded step. In this case the path to `docstrfmt` is
``$PyInterpreterDirectory$/docstrfmt``.
3. Open External tools in PyCharm.
- On macOS:
`PyCharm -> Preferences -> Tools -> External Tools`
- On Windows / Linux / BSD:
`File -> Settings -> Tools -> External Tools`
4. Click the + icon to add a new external tool with the following values:
- Name: docstrfmt
- Description:
- Program: <install_location_from_step_2>
- Arguments: ``"$FilePath$"``
5. Format the currently opened file by selecting `Tools -> External Tools -> docstrfmt`.
- Alternatively, you can set a keyboard shortcut by navigating to `Preferences or
Settings -> Keymap -> External Tools -> External Tools - docstrfmt`.
6. Optionally, run `docstrfmt` on every file save:
1. Make sure you have the `File Watchers
<https://plugins.jetbrains.com/plugin/7177-file-watchers>`_ plugin installed.
2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a
new watcher:
- Name: docstrfmt
- File type: Python
- Scope: Project Files
- Program: <install_location_from_step_2>
- Arguments: ``$FilePath$``
- Output paths to refresh: ``$FilePath$``
- Working directory: ``$ProjectFileDir$``
3. Uncheck "Auto-save edited files to trigger the watcher" in Advanced Options
With pre-commit
~~~~~~~~~~~~~~~
.. code-block:: yaml
repos:
- repo: https://github.com/LilSpazJoekp/docstrfmt
rev: stable # Replace by any tag/version: https://github.com/LilSpazJoekp/docstrfmt/tags
hooks:
- id: docstrfmt
language_version: python3
types_or: [python, rst, txt] # only needed if you want to include txt files.
.. _black: https://github.com/psf/black
.. _blackd: https://github.com/psf/black#blackd
.. _docutils: https://docutils.sourceforge.io/
.. _pandoc: https://pandoc.org/
.. _reformatter.el: https://github.com/purcell/reformatter.el
.. _restructuredtext: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
.. _rstfmt: https://github.com/dzhu/rstfmt
.. _rustfmt: https://github.com/rust-lang/rustfmt
Raw data
{
"_id": null,
"home_page": "https://github.com/LilSpazJoekp/docstrfmt",
"name": "docstrfmt",
"maintainer": "",
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Joel Payne",
"author_email": "lilspazjoekp@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f5/81/69b125a2b8a5f3282d16ea4ba3935949992897e48378fde7f7f94fd59496/docstrfmt-1.6.0.tar.gz",
"platform": null,
"description": "docstrfmt: a formatter for Sphinx flavored reStructuredText\n===========================================================\n\n.. image:: https://img.shields.io/pypi/v/docstrfmt.svg\n :alt: Latest docstrfmt Version\n :target: https://pypi.python.org/pypi/docstrfmt\n\n.. image:: https://img.shields.io/pypi/pyversions/docstrfmt\n :alt: Supported Python Versions\n :target: https://pypi.python.org/pypi/docstrfmt\n\n.. image:: https://img.shields.io/pypi/dm/docstrfmt\n :alt: PyPI - Downloads - Monthly\n :target: https://pypi.python.org/pypi/docstrfmt\n\n.. image:: https://coveralls.io/repos/github/LilSpazJoekp/docstrfmt/badge.svg?branch=master\n :alt: Coveralls Coverage\n :target: https://coveralls.io/github/LilSpazJoekp/docstrfmt?branch=master\n\n.. image:: https://github.com/LilSpazJoekp/docstrfmt/workflows/CI/badge.svg\n :alt: Github Actions Coverage\n :target: https://github.com/LilSpazJoekp/docstrfmt/actions?query=branch%3Amaster\n\n.. image:: https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg\n :alt: Contributor Covenant\n :target: https://github.com/ilSpazJoekp/docstrfmt/blob/master/CODE_OF_CONDUCT.md\n\n*Strongly inspired by* rstfmt_ and rustfmt_.\n\n*This is considered to be in beta however it is mostly stable.*\n\nDescription\n-----------\n\ndocstrfmt is a tool for automatically formatting reStructuredText_ in files and Python\ndocstrings in a consistent way.\n\nLike Black_ and rstfmt_, the motivation is to provide a format that is reasonable and\nminimally configurable to prevent teams from wasting time on style discussions (or\nindividuals on manually doing formatting, for that matter).\n\nCurrently, docstrfmt is in an early stage of development. The most common reST\nconstructs are covered but there are some that are not. If there is a construct missing\nand would like to add it, feel free to open a PR to add it or open an issue and I'll see\nwhat I can do.\n\nTo get a feel for the output of docstrfmt, see `the sample file <sample.rst>`__.\n\nDifferences between docstrfmt and rstfmt_\n-----------------------------------------\n\nThe main difference between rstfmt_ and docstrfmt is the ability to format Python\ndocstrings. I am open to merging this project with rstfmt_, however, there as several\ndifferences in formatting conventions between the two (hence the separate fork).\n\nUsage\n-----\n\n.. code-block:: sh\n\n # Install.\n pip install docstrfmt\n\n # Install the development version.\n pip install https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip\n\n # Read a file from stdin and write the formatted version to stdout.\n docstrfmt\n\n # Format the given file(s) in place.\n docstrfmt <file>...\n\n # Format the given files, printing all output to stdout.\n docstrfmt -o <file>...\n\n # Wrap paragraphs to the given line length where possible (default 88).\n docstrfmt -l <length>\n\nLike Black's blackd_, there is also a daemon that provides formatting via HTTP requests\nto avoid the cost of starting and importing everything on every run.\n\n.. code-block:: sh\n\n # Install.\n pip install \"docstrfmt[d]\"\n\n # Install the development version.\n pip install \"https://github.com/LilSpazJoekp/docstrfmt/archive/master.zip#egg=docstrfmt[d]\"\n\n # Start the daemon (binds to localhost:5219 by default).\n docstrfmtd --bind-host=<host> --bind-port=<port>\n\n # Print the formatted version of a file.\n curl http://locahost:5219 --data-binary @<file>\n\n # Specify the line length (default 88).\n curl -H 'X-Line-Length: 72' http://locahost:5219 --data-binary @<file>\n\n # Mimic the standalone tool: read from stdin, write to stdout, exit with\n # a nonzero status code if there are errors.\n curl -fsS http://locahost:5219 --data-binary @/dev/stdin\n\nWith editors\n~~~~~~~~~~~~\n\nPyCharm\n+++++++\n\nInstructions derived from `black documentation\n<https://black.readthedocs.io/en/stable/editor_integration.html#pycharm-intellij-idea>`_\n\n1. Install.\n\n .. code-block:: sh\n\n pip install \"docstrfmt[d]\"\n\n2. Locate where `docstrfmt` is installed.\n\n - On macOS / Linux / BSD:\n\n .. code-block:: sh\n\n which docstrfmt\n # /usr/local/bin/docstrfmt # possible location\n\n - On Windows:\n\n .. code-block:: shell\n\n where docstrfmt\n # C:\\Program Files\\Python39\\Scripts\\docstrfmt.exe\n\n.. note::\n\n Note that if you are using a virtual environment detected by PyCharm, this is an\n unneeded step. In this case the path to `docstrfmt` is\n ``$PyInterpreterDirectory$/docstrfmt``.\n\n3. Open External tools in PyCharm.\n\n - On macOS:\n\n `PyCharm -> Preferences -> Tools -> External Tools`\n\n - On Windows / Linux / BSD:\n\n `File -> Settings -> Tools -> External Tools`\n\n4. Click the + icon to add a new external tool with the following values:\n\n - Name: docstrfmt\n - Description:\n - Program: <install_location_from_step_2>\n - Arguments: ``\"$FilePath$\"``\n\n5. Format the currently opened file by selecting `Tools -> External Tools -> docstrfmt`.\n\n - Alternatively, you can set a keyboard shortcut by navigating to `Preferences or\n Settings -> Keymap -> External Tools -> External Tools - docstrfmt`.\n\n6. Optionally, run `docstrfmt` on every file save:\n\n 1. Make sure you have the `File Watchers\n <https://plugins.jetbrains.com/plugin/7177-file-watchers>`_ plugin installed.\n 2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a\n new watcher:\n\n - Name: docstrfmt\n - File type: Python\n - Scope: Project Files\n - Program: <install_location_from_step_2>\n - Arguments: ``$FilePath$``\n - Output paths to refresh: ``$FilePath$``\n - Working directory: ``$ProjectFileDir$``\n\n 3. Uncheck \"Auto-save edited files to trigger the watcher\" in Advanced Options\n\nWith pre-commit\n~~~~~~~~~~~~~~~\n\n.. code-block:: yaml\n\n repos:\n - repo: https://github.com/LilSpazJoekp/docstrfmt\n rev: stable # Replace by any tag/version: https://github.com/LilSpazJoekp/docstrfmt/tags\n hooks:\n - id: docstrfmt\n language_version: python3\n types_or: [python, rst, txt] # only needed if you want to include txt files.\n\n.. _black: https://github.com/psf/black\n\n.. _blackd: https://github.com/psf/black#blackd\n\n.. _docutils: https://docutils.sourceforge.io/\n\n.. _pandoc: https://pandoc.org/\n\n.. _reformatter.el: https://github.com/purcell/reformatter.el\n\n.. _restructuredtext: https://docutils.sourceforge.io/docs/user/rst/quickstart.html\n\n.. _rstfmt: https://github.com/dzhu/rstfmt\n\n.. _rustfmt: https://github.com/rust-lang/rustfmt\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A formatter for Sphinx flavored reStructuredText.",
"version": "1.6.0",
"project_urls": {
"Homepage": "https://github.com/LilSpazJoekp/docstrfmt"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2634b5f82041b28a68e934f1cfc3b8f0d430f5ed09a85d83ca1b10396b822312",
"md5": "b8e13ae5e6d3a385e211c5d603d26ddc",
"sha256": "4a54b670658ce24e3f91f7ef1e48a8efcc8f457d7e4b2afc5e705f5259ecfcba"
},
"downloads": -1,
"filename": "docstrfmt-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8e13ae5e6d3a385e211c5d603d26ddc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 28138,
"upload_time": "2023-12-10T17:41:44",
"upload_time_iso_8601": "2023-12-10T17:41:44.703559Z",
"url": "https://files.pythonhosted.org/packages/26/34/b5f82041b28a68e934f1cfc3b8f0d430f5ed09a85d83ca1b10396b822312/docstrfmt-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f58169b125a2b8a5f3282d16ea4ba3935949992897e48378fde7f7f94fd59496",
"md5": "2fc85dda7a620e8b27fc5157942583fb",
"sha256": "92ab25e1165e6e7228145053fcc63127ab0952d0597f6dab497c00b19b84d0e2"
},
"downloads": -1,
"filename": "docstrfmt-1.6.0.tar.gz",
"has_sig": false,
"md5_digest": "2fc85dda7a620e8b27fc5157942583fb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 43868,
"upload_time": "2023-12-10T17:41:47",
"upload_time_iso_8601": "2023-12-10T17:41:47.207199Z",
"url": "https://files.pythonhosted.org/packages/f5/81/69b125a2b8a5f3282d16ea4ba3935949992897e48378fde7f7f94fd59496/docstrfmt-1.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-10 17:41:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LilSpazJoekp",
"github_project": "docstrfmt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docstrfmt"
}
JSON
