Add support for reStructuredText literal blocks

[carltongibson]

This is initial sketch to fix #195. It adds processing for Sphinx' default language blocks, marked with paragraphs ending ::, which is common to all Sphinx projects using the defaults there (i.e. sphinx-quickstart generated).

• No doubt there's a wiggle or two in the regex, that we'll no doubt find running it against Django's docs.
• Would need a CLI flag. a121cc0
• ... (what else) ...

Opening early for input, and to let us experiment on the Django docs.

[adamchainz]

Okay picking this up, let’s do it.

I’ve rebased the PR on top of recent CI changes.

I renamed the flag to --rst-literal-blocks - that’s the name of the reStructuredText element that we’re attempting to parse, so it seems fair to call the flag that. I added some more explainer in the docs.

I then tried runnign the updated version against Django by adding my local repo to pre-commit:

  - repo: /Users/chainz/Documents/Projects/blacken-docs
    rev: baebf4ad8463b71ad8a2781486858ee24d665c3b
    hooks:
      - id: blacken-docs
        files: '\.txt$'
        args: [--rst-literal-blocks]

I noticed many failures from directives like .. warning::, for which I’ve added a test case and fixed the regex. The lookahead assertion needed to be at the start, to avoid regex backtracking and matching indent as ''.

Would you like to review this and also try it out again on Django before we merge? or @jvzammit?

[adamchainz]

I just fixed a crash case seen on Django docs, for empty literal blocks, like in docs/ref/models/expressions.txt:

Example::

.. code-block:: python

  def relabeled_clone(self, change_map):
      clone = copy.copy(self)
      clone.expression = self.expression.relabeled_clone(change_map)
      return clone

There are a whole bunch of code parse errors to fix up, even on the branch of django/django#16261 . But from a random sampling none seem to be problems with the regex now.

[adamchainz]

We have another failing test case - literal blocks inside code blocks:

How to do literal blocks:

.. code-block:: rst

    A literal block::

        This is not Python.

Since this is probably rare enough in practice, I'm gonna make that a separate issue.

I'm doing some other work to “standardize” this repo so I'll merge this now and release in a bit. We can refine it later if needed, it is at least behind a flag.