{"author":null,"author_email":"Anthony Sottile ","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Intended Audience :: Developers","License :: OSI Approved :: MIT License","Natural Language :: English","Operating System :: OS Independent","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: 3.9","Typing :: Typed"],"description":"============\nblacken-docs\n============\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/blacken-docs/main.yml.svg?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 `__ 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.9 to 3.13 supported.\n\nBlack 22.1.0+ supported.\n\npre-commit hook\n---------------\n\nYou can also install blacken-docs as a `pre-commit `__ hook.\nAdd the following to the ``repos`` section of your ``.pre-commit-config.yaml`` file (`docs `__):\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’s best to pin it in ``additional_dependencies``, and upgrade as appropriate.\nIf you have Black installed as another hook, you can automate upgrading this pinned hook using `sync-pre-commit-deps `__.\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…or PowerShell’s |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* |--pyi|__\n\n .. |--pyi| replace:: ``--pyi``\n __ https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#pyi\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* ``--check`` - Don’t modify files but indicate when changes are necessary with a message and non-zero return code.\n* ``-E`` / ``--skip-errors`` - Don’t 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 `__ 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 “python” blocks:\n\n.. code-block:: markdown\n\n ```python\n def hello():\n print(\"hello world\")\n ```\n\nAnd “pycon” blocks:\n\n.. code-block:: markdown\n\n ```pycon\n\n >>> def hello():\n ... print(\"hello world\")\n ...\n\n ```\n\nPrevent formatting within a block using ``blacken-docs:off`` and ``blacken-docs:on`` comments:\n\n.. code-block:: markdown\n\n \n ```python\n # whatever you want\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 “python” blocks:\n\n.. code-block:: rst\n\n .. code-block:: python\n\n def hello():\n print(\"hello world\")\n\nIn “pycon” blocks:\n\n.. code-block:: rst\n\n .. code-block:: pycon\n\n >>> def hello():\n ... print(\"hello world\")\n ...\n\nPrevent formatting within a block using ``blacken-docs:off`` and ``blacken-docs:on`` comments:\n\n.. code-block:: rst\n\n .. blacken-docs:off\n\n .. code-block:: python\n\n # whatever you want\n\n .. blacken-docs:on\n\nUse ``--rst-literal-blocks`` to also format `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 `__.\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 “python” blocks:\n\n.. code-block:: latex\n\n \\begin{minted}{python}\n def hello():\n print(\"hello world\")\n \\end{minted}\n\nIn minted “pycon” 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\nPrevent formatting within a block using ``blacken-docs:off`` and ``blacken-docs:on`` comments:\n\n.. code-block:: latex\n\n % blacken-docs:off\n \\begin{minted}{python}\n # whatever you want\n \\end{minted}\n % blacken-docs:on\n","description_content_type":"text/x-rst","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":null,"license":null,"license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":"Adam Johnson ","name":"blacken-docs","package_url":"https://pypi.org/project/blacken-docs/","platform":null,"project_url":"https://pypi.org/project/blacken-docs/","project_urls":{"Changelog":"https://github.com/adamchainz/blacken-docs/blob/main/CHANGELOG.rst","Repository":"https://github.com/asottile/blacken-docs"},"provides_extra":null,"release_url":"https://pypi.org/project/blacken-docs/1.19.1/","requires_dist":["black>=22.1"],"requires_python":">=3.9","summary":"Run Black on Python code blocks in documentation files.","version":"1.19.1","yanked":false,"yanked_reason":null}

Package search

blacken-docs

project_urls

Dependencies

All package metadata

Releases