Handle Python code in docs (ReST, markdown etc)

[blueyed]

It would be nice if black would also handle Python code blocks in documentation files (reStructuredText, markdown etc).

(via pytest-dev/pytest#3525 (comment))

[asottile]

hah, I had the same idea: #292

[blueyed]

Heh..
Your issue seems to be a bit broader, and would be possible probably already, given that you could extract code blocks, run black on them and then replace them (kind of an API usage).

What I had in mind would be that black could be just run on documentation files, and would handle all code blocks in there.

Let's wait for some feedback from maintainer(s).

[ambv]

Sounds interesting, it would require a lot more dependencies to be added to Black though to enable parsing Markdown, ReST, and so on. I'll leave this open as I am not opposed to the idea. However, there are more urgent things we need to implement/fix before we can think about this.

[asottile]

I'm going to take a stab at implementing this in a separate project, maybe at some point it could be merged back into core

[asottile]

It lives! https://github.com/asottile/blacken-docs

Here's an example PR of what it can do: pytest-dev/pytest#3528

[hauntsaninja]

Thank you! Given the existence of tools like https://github.com/adamchainz/blacken-docs and https://github.com/hukkin/mdformat-black, I don't think we should include this in Black proper. The long tail of formats is best dealt with by the ecosystem and we should do things like #779 to help support the ecosystem build on Black.