在文档文件中运行Black对Python代码块。
项目描述
在文档文件中运行Black对Python代码块。
安装
使用 pip
python -m pip install blacken-docs支持Python 3.8到3.12。
支持Black 22.1.0+
pre-commit钩子
您还可以将blacken-docs安装为pre-commit钩子。将以下内容添加到您的repos部分.pre-commit-config.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然后，重新格式化整个项目
pre-commit run blacken-docs --all-files由于Black是一个不断发展的目标，因此最好在additional_dependencies中将其固定，并根据需要进行升级。如果您已将Black安装为另一个钩子，则可以使用sync-pre-commit-deps自动化升级此固定的钩子。
使用方法
blacken-docs是一个命令行工具，它可以就地重写文档文件。它支持Markdown、reStructuredText和LaTeX文件。此外，您还可以在Python文件上运行它，以重新格式化文档字符串中的Markdown和reStructuredText。
使用要重写的文件名运行blacken-docs
blacken-docs README.rst如果任何文件已修改，则blacken-docs将退出非零。
blacken-docs 没有递归遍历目录的能力。请使用 pre-commit 集成、通配符或其他技术来应用于多个文件。例如，可以使用 以下方法：git ls-files | xargs
git ls-files -z -- '*.md' | xargs -0 blacken-docs…或者 PowerShell 的 ForEach-Object
git ls-files -- '*.md' | %{blacken-docs $_}blacken-docs 当前将以下选项传递给 Black
它还具有以下额外选项
--check - 不要修改文件，但通过消息和非零返回码指示何时需要更改。
-E / --skip-errors - 对于 Black 的错误（通常为语法错误）不退出非零。
--rst-literal-blocks - 同时格式化 reStructuredText 文件中的文本块（下面详细介绍）。
历史
blacken-docs 由 Anthony Sottile 在 2018 年创建。到 2022 年底，Adam Johnson 接管了维护工作。
支持的代码块格式
blacken-docs 格式与以下模式匹配的代码块。
Markdown
在“python”块中
```python
def hello():
print("hello world")
```以及“pycon”块中
```pycon
>>> def hello():
... print("hello world")
...
```使用 blacken-docs:off 和 blacken-docs:on 注释防止块内的格式化
<!-- blacken-docs:off -->
```python
# whatever you want
```
<!-- blacken-docs:on -->在 Python 文件中，包含 Markdown 代码块的文档字符串可以被重新格式化
def f():
"""docstring here
```python
print("hello world")
```
"""reStructuredText
在“python”块中
.. code-block:: python
def hello():
print("hello world")在“pycon”块中
.. code-block:: pycon
>>> def hello():
... print("hello world")
...使用 blacken-docs:off 和 blacken-docs:on 注释防止块内的格式化
.. blacken-docs:off
.. code-block:: python
# whatever you want
.. blacken-docs:on使用 --rst-literal-blocks 也可以格式化 文本块
An example::
def hello():
print("hello world")文本块用 :: 标记，默认情况下可以是任何等宽文本。但是，Sphinx 将它们默认解释为 Python 代码 。如果您的项目使用 Sphinx 并且有这种配置，请添加 --rst-literal-blocks 来格式化此类块。
在 Python 文件中，包含 reStructuredText 代码块的文档字符串可以被重新格式化
def f():
"""docstring here
.. code-block:: python
print("hello world")
"""LaTeX
在 minted “python” 块中
\begin{minted}{python}
def hello():
print("hello world")
\end{minted}在 minted “pycon” 块中
\begin{minted}{pycon}
>>> def hello():
... print("hello world")
...
\end{minted}在 PythonTeX 块中
\begin{pycode}
def hello():
print("hello world")
\end{pycode}使用 blacken-docs:off 和 blacken-docs:on 注释防止块内的格式化
% blacken-docs:off
\begin{minted}{python}
# whatever you want
\end{minted}
% blacken-docs:on
下载文件
下载适用于您平台的应用程序。如果您不确定选择哪个，请了解更多关于 安装包 的信息。
源代码发行版
构建分发版本
blacken_docs-1.18.0.tar.gz 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 47bed628679d008a8eb55d112df950582e68d0f57615223929e366348d935444 |
|
| MD5 | c59a08f777fb8ae697952073b41a5871 |
|
| BLAKE2b-256 | 12a999fe0283575297466df65eb54873a892f0db5fd24459abef4c2691db883a |
blacken_docs-1.18.0-py3-none-any.whl 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | 64f592246784131e9f84dad1db397f44eeddc77fdf01726bab920a3f00a3815c |
|
| MD5 | b35484256d4b05039acd768596689307 |
|
| BLAKE2b-256 | 3d7e532f6c8b81346c2337c54b0e16f49f2968d86b0c535d6318b3f21f3ff4cf |