Format python code blocks in documentation files

[Paolo Melchiorre]

Now that we use Black for formatting the Django code, I think it would help a lot to format the Python code blocks present in the documentation with Black as well.

This would help those learning Django to find consistency between the code format that is present in the documentation and that present in the GIT repository.

It would also help the volunteers contributing to the documentation to have a clear guideline on the format of the sample Python code and an automatic formatter that relieves them of the worry of making mistakes.

I only know the Adam's ​blacken-docs to achieve the goal but if I know others I invite them to propose them.

[benjaoming]

This sounds like a really good idea!

We have added the mentioned pre-commit hook "blacken-docs" Read the Docs codebase. It has worked really well -- aside from "cosmetic" changes, it also fixed a couple of wrong indentations.

Here is the result: ​https://github.com/readthedocs/readthedocs.org/pull/9672

Perhaps blacken-docs lacks a good option to switch off black'ening for a certain code segment. But so far, we haven't had that issue. It's worth running it on the entire documentation project to check that there isn't any segments that are intentionally non-conformative with black.

[Joseph V Zammit]

Hi Paolo, what does this involve? I see these steps:

1. Install ​blacken-docs on my local and run it against current docs.
2. Manually inspect the result. If things look good move to step 3.
3. Add blacken-docs to the docs pre-commit configuration, as suggested here.
4. Add blacken-docs to the current docs CI steps. (I might have questions on this.)

Does this make sense? Am I missing something?

[Paolo Melchiorre]

Hi Joseph, yes I think these are the steps to do, and if others, as I hope, would agree, we can merge it.
Feel free to open a PR and then add the URL here.

[Joseph V Zammit]

Hi Paolo, and whoever can guide me on this. I opened a PR with some initial work I put into this. Why "initial"? I feel there are some questions that need to be answered. All in the PR here:

​https://github.com/django/django/pull/16261

Thanks!

[Paolo Melchiorre]

Thanks for your work on this issue. I commented your PR.

[Carlton Gibson]

I think we should probably do this. +1

[Mariusz Felisiak <felisiak.mariusz@…>]

In 534ac482:

Refs #34140 -- Applied rst code-block to non-Python examples.

Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for
reviews.

[Mariusz Felisiak <felisiak.mariusz@…>]

In b784768e:

[4.2.x] Refs #34140 -- Applied rst code-block to non-Python examples.

Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for
reviews.

Backport of 534ac4829764f317cf2fbc4a18354fcc998c1425 from main.

[Mariusz Felisiak <felisiak.mariusz@…>]

In ba755ca:

Refs #34140 -- Corrected rst code-block and various formatting issues in docs.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 5bdd6223:

[4.2.x] Refs #34140 -- Corrected rst code-block and various formatting issues in docs.

Backport of ba755ca13123d2691a0926ddb64e5d0a2906a880 from main

[Mariusz Felisiak]

​PR

[Mariusz Felisiak <felisiak.mariusz@…>]

In 9cf2a5df:

Refs #34140 -- Made minor edits to rst code-blocks.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 6015bab8:

Refs #34140 -- Added configurations to run blacken-docs linter and adjusted docs.

This adds:

• GitHub actions,
• tox configuration,
• pre-commit hook, and
• makefile rules

to run blacken-docs linter.

Co-authored-by: David Smith <smithdc@…>

[Mariusz Felisiak <felisiak.mariusz@…>]

In 14459f8:

Fixed #34140 -- Reformatted code blocks in docs with blacken-docs.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 8d2ac000:

[4.2.x] Refs #34140 -- Made minor edits to rst code-blocks.

Backport of 9cf2a5df70051dffcefe21c6b27203e2d5804922 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 32f224e:

[4.2.x] Refs #34140 -- Added configurations to run blacken-docs linter and adjusted docs.

This adds:

• GitHub actions,
• tox configuration,
• pre-commit hook, and
• makefile rules

to run blacken-docs linter.

Co-authored-by: David Smith <smithdc@…>

Backport of 6015bab80e28aef2669f6fac53423aa65f70cb08 from main

[Mariusz Felisiak <felisiak.mariusz@…>]

In 62510f0:

[4.2.x] Fixed #34140 -- Reformatted code blocks in docs with blacken-docs.

[GitHub <noreply@…>]

In d89a465e:

Refs #34140 -- Fixed blacken-docs pre-commit configuration.

Missed in 6015bab80e28aef2669f6fac53423aa65f70cb08. The default
blacken-docs hook definition does not apply to .txt files, which the
Django documentation uses. This commit overrides that definition to
point blacken-docs at the appropriate files.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 45fae656:

[5.0.x] Refs #34140 -- Fixed blacken-docs pre-commit configuration.

Missed in 6015bab80e28aef2669f6fac53423aa65f70cb08. The default
blacken-docs hook definition does not apply to .txt files, which the
Django documentation uses. This commit overrides that definition to
point blacken-docs at the appropriate files.
Backport of d89a465e62ad876cc7f1332d1712700cb81f3995 from main