From 96748fccf22936a335e6cc8ee3e5da62928e1924 Mon Sep 17 00:00:00 2001
From: Adam Johnson <me@adamj.eu>
Date: Mon, 16 Jan 2023 10:17:30 +0000
Subject: [PATCH] Improve README

---
 README.md  | 143 ------------------------------------
 README.rst | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 setup.cfg  |   6 +-
 3 files changed, 212 insertions(+), 146 deletions(-)
 delete mode 100644 README.md
 create mode 100644 README.rst

diff --git a/README.md b/README.md
deleted file mode 100644
index 11acba5..0000000
--- a/README.md
+++ /dev/null
@@ -1,143 +0,0 @@
-[![Build Status](https://dev.azure.com/asottile/asottile/_apis/build/status/asottile.blacken-docs?branchName=main)](https://dev.azure.com/asottile/asottile/_build/latest?definitionId=36&branchName=main)
-[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/asottile/blacken-docs/main.svg)](https://results.pre-commit.ci/latest/github/asottile/blacken-docs/main)
-
-blacken-docs
-============
-
-Run `black` on python code blocks in documentation files.
-
-## install
-
-```bash
-pip install blacken-docs
-```
-
-## usage
-
-`blacken-docs` provides a single executable (`blacken-docs`) which will modify
-`.rst` / `.md` / `.tex` files in place.
-
-If a file is modified, `blacken-docs` exits nonzero.
-
-It currently supports the following [`black`](https://github.com/psf/black)
-options:
-
-- `-l` / `--line-length`
-- `-t` / `--target-version`
-- `-S` / `--skip-string-normalization`
-
-Following additional parameters can be used:
-
- - `-E` / `--skip-errors`
- - `--rst-literal-blocks`
-
-`blacken-docs` will format code in the following block types:
-
-(markdown)
-```markdown
-    ```python
-    def hello():
-        print("hello world")
-    ```
-```
-
-(markdown `pycon`)
-```markdown
-    ```pycon
-
-    >>> def hello():
-    ...     print("hello world")
-    ...
-
-    ```
-```
-
-(rst)
-```rst
-    .. code-block:: python
-
-        def hello():
-            print("hello world")
-```
-
-This style is enabled with the `--use-sphinx-default` option.
-
-(rst `pycon`)
-```rst
-    .. code-block:: pycon
-
-        >>> def hello():
-        ...     print("hello world")
-        ...
-```
-
-(rst literal blocks - activated with ``--rst-literal-blocks``)
-
-reStructuredText [literal blocks](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#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.
-
-``rst
-    An example::
-
-        def hello():
-            print("hello world")
-```
-
-(latex)
-```latex
-\begin{minted}{python}
-def hello():
-    print("hello world")
-\end{minted}
-```
-
-(latex `pycon`)
-```latex
-\begin{minted}{pycon}
->>> def hello():
-...     print("hello world")
-...
-\end{minted}
-```
-
-(latex with pythontex)
-```latex
-\begin{pycode}
-def hello():
-    print("hello world")
-\end{pycode}
-```
-
-(markdown/rst in python docstrings)
-```python
-def f():
-    """docstring here
-
-    .. code-block:: python
-
-        print("hello world")
-
-    ```python
-    print("hello world")
-    ```
-    """
-```
-
-## usage with pre-commit
-
-See [pre-commit](https://pre-commit.com) for instructions
-
-Sample `.pre-commit-config.yaml`:
-
-
-```yaml
--   repo: https://github.com/adamchainz/blacken-docs
-    rev: v1.12.1
-    hooks:
-    -   id: blacken-docs
-        additional_dependencies: [black==...]
-```
-
-Since `black` is currently a moving target, it is suggested to pin `black`
-to a specific version using `additional_dependencies`.
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..9d1c78a
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,209 @@
+============
+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.7 to 3.11 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 commandline 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 currently passes the following options through to Black:
+
+* ``-l`` / ``--line-length``
+* ``-t`` / ``--target-version``
+* ``-S`` / ``--skip-string-normalization``
+
+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}
diff --git a/setup.cfg b/setup.cfg
index 2141c5d..e981fbd 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -1,9 +1,9 @@
 [metadata]
 name = blacken_docs
 version = 1.12.1
-description = Run `black` on python code blocks in documentation files
-long_description = file: README.md
-long_description_content_type = text/markdown
+description = Run Black on Python code blocks in documentation files.
+long_description = file: README.rst
+long_description_content_type = text/rst
 url = https://github.com/asottile/blacken-docs
 author = Anthony Sottile
 author_email = asottile@umich.edu