Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add support for reStructuredText literal blocks #196

Merged
merged 9 commits into from
Jan 16, 2023

Conversation

carltongibson
Copy link
Contributor

@carltongibson carltongibson commented Dec 1, 2022

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 adamchainz changed the title Added regex for Sphinx default language blocks. Add support for reStructuredText literal blocks Jan 15, 2023
@adamchainz
Copy link
Owner

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 adamchainz mentioned this pull request Jan 15, 2023
@adamchainz
Copy link
Owner

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
Copy link
Owner

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

RST: Detect :: signifying default language code-block.
2 participants