Opened 2 years ago

Closed 22 months ago

Last modified 11 months ago

#34140 closed Cleanup/optimization (fixed)

Format python code blocks in documentation files

Reported by: Paolo Melchiorre Owned by: Joseph V Zammit
Component: Documentation Version: dev
Severity: Normal Keywords: format, black, snippet, example
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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.

Change History (20)

comment:1 by benjaoming, 2 years ago

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.

comment:2 by Joseph V Zammit, 2 years ago

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?

comment:3 by Paolo Melchiorre, 2 years ago

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.

comment:4 by Joseph V Zammit, 2 years ago

Owner: changed from nobody to Joseph V Zammit
Status: newassigned

comment:5 by Joseph V Zammit, 2 years ago

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!

comment:6 by Paolo Melchiorre, 2 years ago

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

comment:7 by Carlton Gibson, 2 years ago

Triage Stage: UnreviewedAccepted

I think we should probably do this. +1

comment:8 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

In 534ac482:

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

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

comment:9 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

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.

comment:10 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

In ba755ca:

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

comment:11 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

In 5bdd6223:

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

Backport of ba755ca13123d2691a0926ddb64e5d0a2906a880 from main

comment:12 by Mariusz Felisiak, 22 months ago

Has patch: set

comment:13 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

In 9cf2a5df:

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

comment:14 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

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@…>

comment:15 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

Resolution: fixed
Status: assignedclosed

In 14459f8:

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

comment:16 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

In 8d2ac000:

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

Backport of 9cf2a5df70051dffcefe21c6b27203e2d5804922 from main

comment:17 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

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

comment:18 by Mariusz Felisiak <felisiak.mariusz@…>, 22 months ago

In 62510f0:

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

comment:19 by GitHub <noreply@…>, 11 months ago

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.

comment:20 by Mariusz Felisiak <felisiak.mariusz@…>, 11 months ago

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

Note: See TracTickets for help on using tickets.
Back to Top