============
blacken-docs
============
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/blacken-docs/main.yml?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI
.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
:target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/blacken-docs.svg?style=for-the-badge
:target: https://pypi.org/project/blacken-docs/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
Run `Black <https://pypi.org/project/black/>`__ on Python code blocks in documentation files.
Installation
============
Use **pip**:
.. code-block:: sh
python -m pip install blacken-docs
Python 3.8 to 3.12 supported.
Black 22.1.0+ supported.
pre-commit hook
---------------
You can also install blacken-docs as a `pre-commit <https://pre-commit.com/>`__ hook.
Add the following to the ``repos`` section of your ``.pre-commit-config.yaml`` file (`docs <https://pre-commit.com/#plugins>`__):
.. code-block:: yaml
- repo: https://github.com/adamchainz/blacken-docs
rev: "" # replace with latest tag on GitHub
hooks:
- id: blacken-docs
additional_dependencies:
- black==22.12.0
Then, reformat your entire project:
.. code-block:: sh
pre-commit run blacken-docs --all-files
Since Black is a moving target, it’s best to pin it in ``additional_dependencies``.
Upgrade as appropriate.
Usage
=====
blacken-docs is a command line tool that rewrites documentation files in place.
It supports Markdown, reStructuredText, and LaTex files.
Additionally, you can run it on Python files to reformat Markdown and reStructuredText within docstrings.
Run ``blacken-docs`` with the filenames to rewrite:
.. code-block:: sh
blacken-docs README.rst
If any file is modified, ``blacken-docs`` exits nonzero.
``blacken-docs`` does not have any ability to recurse through directories.
Use the pre-commit integration, globbing, or another technique for applying to many files.
For example, |with git ls-files pipe xargs|_:
.. |with git ls-files pipe xargs| replace:: with ``git ls-files | xargs``
.. _with git ls-files pipe xargs: https://adamj.eu/tech/2022/03/09/how-to-run-a-command-on-many-files-in-your-git-repository/
.. code-block:: sh
git ls-files -z -- '*.md' | xargs -0 blacken-docs
…or PowerShell’s |ForEach-Object|__:
.. |ForEach-Object| replace:: ``ForEach-Object``
__ https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object
.. code-block:: powershell
git ls-files -- '*.md' | %{blacken-docs $_}
blacken-docs currently passes the following options through to Black:
* |-l / --line-length|__
.. |-l / --line-length| replace:: ``-l`` / ``--line-length``
__ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#l-line-length
* |--preview|__
.. |--preview| replace:: ``--preview``
__ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#preview
* |-S / --skip-string-normalization|__
.. |-S / --skip-string-normalization| replace:: ``-S`` / ``--skip-string-normalization``
__ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#s-skip-string-normalization
* |-t / --target-version|__
.. |-t / --target-version| replace:: ``-t`` / ``--target-version``
__ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#t-target-version
It also has the below extra options:
* ``-E`` / ``--skip-errors`` - Don’t exit non-zero for errors from Black (normally syntax errors).
* ``--rst-literal-blocks`` - Also format literal blocks in reStructuredText files (more below).
History
=======
blacken-docs was created by `Anthony Sottile <https://github.com/asottile/>`__ in 2018.
At the end of 2022, Adam Johnson took over maintenance.
Supported code block formats
============================
blacken-docs formats code blocks matching the following patterns.
Markdown
--------
In “python” blocks:
.. code-block:: markdown
```python
def hello():
print("hello world")
```
And “pycon” blocks:
.. code-block:: markdown
```pycon
>>> def hello():
... print("hello world")
...
```
Within Python files, docstrings that contain Markdown code blocks may be reformatted:
.. code-block:: python
def f():
"""docstring here
```python
print("hello world")
```
"""
reStructuredText
----------------
In “python” blocks:
.. code-block:: rst
.. code-block:: python
def hello():
print("hello world")
In “pycon” blocks:
.. code-block:: rst
.. code-block:: pycon
>>> def hello():
... print("hello world")
...
Use ``--rst-literal-blocks`` to also format `literal blocks <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks>`__:
.. code-block:: rst
An example::
def hello():
print("hello world")
Literal blocks are marked with ``::`` and can be any monospaced text by default.
However Sphinx interprets them as Python code `by default <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks>`__.
If your project uses Sphinx and such a configuration, add ``--rst-literal-blocks`` to also format such blocks.
Within Python files, docstrings that contain reStructuredText code blocks may be reformatted:
.. code-block:: python
def f():
"""docstring here
.. code-block:: python
print("hello world")
"""
LaTeX
-----
In minted “python” blocks:
.. code-block:: latex
\begin{minted}{python}
def hello():
print("hello world")
\end{minted}
In minted “pycon” blocks:
.. code-block:: latex
\begin{minted}{pycon}
>>> def hello():
... print("hello world")
...
\end{minted}
In PythonTeX blocks:
.. code-block:: latex
\begin{pycode}
def hello():
print("hello world")
\end{pycode}
Raw data
{
"_id": null,
"home_page": "https://github.com/asottile/blacken-docs",
"name": "blacken-docs",
"maintainer": "Adam Johnson",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "me@adamj.eu",
"keywords": "",
"author": "Anthony Sottile",
"author_email": "asottile@umich.edu",
"download_url": "https://files.pythonhosted.org/packages/73/79/a3fbf1d5c1ea3395a2a16e435d918a35d60ac7474cfb41cf34a44acb0127/blacken_docs-1.16.0.tar.gz",
"platform": null,
"description": "============\nblacken-docs\n============\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/blacken-docs/main.yml?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI\n\n.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge\n :target: https://github.com/adamchainz/blacken-docs/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/blacken-docs.svg?style=for-the-badge\n :target: https://pypi.org/project/blacken-docs/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\nRun `Black <https://pypi.org/project/black/>`__ on Python code blocks in documentation files.\n\nInstallation\n============\n\nUse **pip**:\n\n.. code-block:: sh\n\n python -m pip install blacken-docs\n\nPython 3.8 to 3.12 supported.\n\nBlack 22.1.0+ supported.\n\npre-commit hook\n---------------\n\nYou can also install blacken-docs as a `pre-commit <https://pre-commit.com/>`__ hook.\nAdd the following to the ``repos`` section of your ``.pre-commit-config.yaml`` file (`docs <https://pre-commit.com/#plugins>`__):\n\n.. code-block:: yaml\n\n - repo: https://github.com/adamchainz/blacken-docs\n rev: \"\" # replace with latest tag on GitHub\n hooks:\n - id: blacken-docs\n additional_dependencies:\n - black==22.12.0\n\nThen, reformat your entire project:\n\n.. code-block:: sh\n\n pre-commit run blacken-docs --all-files\n\nSince Black is a moving target, it\u2019s best to pin it in ``additional_dependencies``.\nUpgrade as appropriate.\n\nUsage\n=====\n\nblacken-docs is a command line tool that rewrites documentation files in place.\nIt supports Markdown, reStructuredText, and LaTex files.\nAdditionally, you can run it on Python files to reformat Markdown and reStructuredText within docstrings.\n\nRun ``blacken-docs`` with the filenames to rewrite:\n\n.. code-block:: sh\n\n blacken-docs README.rst\n\nIf any file is modified, ``blacken-docs`` exits nonzero.\n\n``blacken-docs`` does not have any ability to recurse through directories.\nUse the pre-commit integration, globbing, or another technique for applying to many files.\nFor example, |with git ls-files pipe xargs|_:\n\n.. |with git ls-files pipe xargs| replace:: with ``git ls-files | xargs``\n.. _with git ls-files pipe xargs: https://adamj.eu/tech/2022/03/09/how-to-run-a-command-on-many-files-in-your-git-repository/\n\n.. code-block:: sh\n\n git ls-files -z -- '*.md' | xargs -0 blacken-docs\n\n\u2026or PowerShell\u2019s |ForEach-Object|__:\n\n.. |ForEach-Object| replace:: ``ForEach-Object``\n__ https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/foreach-object\n\n.. code-block:: powershell\n\n git ls-files -- '*.md' | %{blacken-docs $_}\n\nblacken-docs currently passes the following options through to Black:\n\n* |-l / --line-length|__\n\n .. |-l / --line-length| replace:: ``-l`` / ``--line-length``\n __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#l-line-length\n\n* |--preview|__\n\n .. |--preview| replace:: ``--preview``\n __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#preview\n\n* |-S / --skip-string-normalization|__\n\n .. |-S / --skip-string-normalization| replace:: ``-S`` / ``--skip-string-normalization``\n __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#s-skip-string-normalization\n\n* |-t / --target-version|__\n\n .. |-t / --target-version| replace:: ``-t`` / ``--target-version``\n __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#t-target-version\n\nIt also has the below extra options:\n\n* ``-E`` / ``--skip-errors`` - Don\u2019t exit non-zero for errors from Black (normally syntax errors).\n* ``--rst-literal-blocks`` - Also format literal blocks in reStructuredText files (more below).\n\nHistory\n=======\n\nblacken-docs was created by `Anthony Sottile <https://github.com/asottile/>`__ in 2018.\nAt the end of 2022, Adam Johnson took over maintenance.\n\nSupported code block formats\n============================\n\nblacken-docs formats code blocks matching the following patterns.\n\nMarkdown\n--------\n\nIn \u201cpython\u201d blocks:\n\n.. code-block:: markdown\n\n ```python\n def hello():\n print(\"hello world\")\n ```\n\nAnd \u201cpycon\u201d blocks:\n\n.. code-block:: markdown\n\n ```pycon\n\n >>> def hello():\n ... print(\"hello world\")\n ...\n\n ```\n\nWithin Python files, docstrings that contain Markdown code blocks may be reformatted:\n\n.. code-block:: python\n\n def f():\n \"\"\"docstring here\n\n ```python\n print(\"hello world\")\n ```\n \"\"\"\n\nreStructuredText\n----------------\n\nIn \u201cpython\u201d blocks:\n\n.. code-block:: rst\n\n .. code-block:: python\n\n def hello():\n print(\"hello world\")\n\nIn \u201cpycon\u201d blocks:\n\n.. code-block:: rst\n\n .. code-block:: pycon\n\n >>> def hello():\n ... print(\"hello world\")\n ...\n\nUse ``--rst-literal-blocks`` to also format `literal blocks <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks>`__:\n\n.. code-block:: rst\n\n An example::\n\n def hello():\n print(\"hello world\")\n\nLiteral blocks are marked with ``::`` and can be any monospaced text by default.\nHowever Sphinx interprets them as Python code `by default <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rst-literal-blocks>`__.\nIf your project uses Sphinx and such a configuration, add ``--rst-literal-blocks`` to also format such blocks.\n\nWithin Python files, docstrings that contain reStructuredText code blocks may be reformatted:\n\n.. code-block:: python\n\n def f():\n \"\"\"docstring here\n\n .. code-block:: python\n\n print(\"hello world\")\n \"\"\"\n\nLaTeX\n-----\n\nIn minted \u201cpython\u201d blocks:\n\n.. code-block:: latex\n\n \\begin{minted}{python}\n def hello():\n print(\"hello world\")\n \\end{minted}\n\nIn minted \u201cpycon\u201d blocks:\n\n.. code-block:: latex\n\n \\begin{minted}{pycon}\n >>> def hello():\n ... print(\"hello world\")\n ...\n \\end{minted}\n\nIn PythonTeX blocks:\n\n.. code-block:: latex\n\n \\begin{pycode}\n def hello():\n print(\"hello world\")\n \\end{pycode}\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Run Black on Python code blocks in documentation files.",
"version": "1.16.0",
"project_urls": {
"Changelog": "https://github.com/adamchainz/blacken-docs/blob/main/CHANGELOG.rst",
"Homepage": "https://github.com/asottile/blacken-docs"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3eb8e38f8dc69df5602b86644236d116d59b9bc636bacbabd79b0c802e3a07e1",
"md5": "f0e7e4a8725a697448ebb65cc923b292",
"sha256": "b0dcb84b28ebfb352a2539202d396f50e15a54211e204a8005798f1d1edb7df8"
},
"downloads": -1,
"filename": "blacken_docs-1.16.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f0e7e4a8725a697448ebb65cc923b292",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7626,
"upload_time": "2023-08-16T08:58:38",
"upload_time_iso_8601": "2023-08-16T08:58:38.666425Z",
"url": "https://files.pythonhosted.org/packages/3e/b8/e38f8dc69df5602b86644236d116d59b9bc636bacbabd79b0c802e3a07e1/blacken_docs-1.16.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7379a3fbf1d5c1ea3395a2a16e435d918a35d60ac7474cfb41cf34a44acb0127",
"md5": "3310da34bb5b795c2b8e61723d208bc0",
"sha256": "b4bdc3f3d73898dfbf0166f292c6ccfe343e65fc22ddef5319c95d1a8dcc6c1c"
},
"downloads": -1,
"filename": "blacken_docs-1.16.0.tar.gz",
"has_sig": false,
"md5_digest": "3310da34bb5b795c2b8e61723d208bc0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12964,
"upload_time": "2023-08-16T08:58:40",
"upload_time_iso_8601": "2023-08-16T08:58:40.359374Z",
"url": "https://files.pythonhosted.org/packages/73/79/a3fbf1d5c1ea3395a2a16e435d918a35d60ac7474cfb41cf34a44acb0127/blacken_docs-1.16.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-16 08:58:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "asottile",
"github_project": "blacken-docs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "blacken-docs"
}
JSON
