[Django] #34140: Format python code blocks in documentation files
Django
-------------------------------------+-------------------------------------
Reporter: Paolo | Owner: nobody
Melchiorre |
Type: | Status: new
Cleanup/optimization |
Component: | Version: dev
Documentation | Keywords:
Severity: Normal | format,black,snippet,example
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
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 [https://github.com/adamchainz/blacken-docs
blacken-docs] to achieve the goal but if I know others I invite them to
propose them.
--
Ticket URL: <https://code.djangoproject.com/ticket/34140>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
format,black,snippet,example | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:1>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
format,black,snippet,example | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by 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
[#https://github.com/adamchainz/blacken-docs#usage-with-pre-commit 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?
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:2>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
format,black,snippet,example | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:3>
Django
-------------------------------------+-------------------------------------
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
format,black,snippet,example | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: nobody => Joseph V Zammit
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:4>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
format,black,snippet,example | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by 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!
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:5>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage:
format,black,snippet,example | Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Paolo Melchiorre):
Thanks for your work on this issue. I commented your PR.
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:6>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
format,black,snippet,example |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* stage: Unreviewed => Accepted
Comment:
I think we should probably do this. +1
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:7>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"534ac4829764f317cf2fbc4a18354fcc998c1425" 534ac482]:
{{{
#!CommitTicketReference repository=""
revision="534ac4829764f317cf2fbc4a18354fcc998c1425"
Refs #34140 -- Applied rst code-block to non-Python examples.
Thanks to J.V. Zammit, Paolo Melchiorre, and Mariusz Felisiak for
reviews.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:8>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"b784768eef75afb32f6d2ce7166551a528bce0ec" b784768e]:
{{{
#!CommitTicketReference repository=""
revision="b784768eef75afb32f6d2ce7166551a528bce0ec"
[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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:9>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"ba755ca13123d2691a0926ddb64e5d0a2906a880" ba755ca]:
{{{
#!CommitTicketReference repository=""
revision="ba755ca13123d2691a0926ddb64e5d0a2906a880"
Refs #34140 -- Corrected rst code-block and various formatting issues in
docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"5bdd6223a24b2bcd0ee32251d6f3ce20e934a1dd" 5bdd6223]:
{{{
#!CommitTicketReference repository=""
revision="5bdd6223a24b2bcd0ee32251d6f3ce20e934a1dd"
[4.2.x] Refs #34140 -- Corrected rst code-block and various formatting
issues in docs.
Backport of ba755ca13123d2691a0926ddb64e5d0a2906a880 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:11>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* has_patch: 0 => 1
Comment:
[https://github.com/django/django/pull/16609 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"6015bab80e28aef2669f6fac53423aa65f70cb08" 6015bab8]:
{{{
#!CommitTicketReference repository=""
revision="6015bab80e28aef2669f6fac53423aa65f70cb08"
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 <smi...@gmail.com>
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"9cf2a5df70051dffcefe21c6b27203e2d5804922" 9cf2a5df]:
{{{
#!CommitTicketReference repository=""
revision="9cf2a5df70051dffcefe21c6b27203e2d5804922"
Refs #34140 -- Made minor edits to rst code-blocks.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:13>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"14459f80ee3a9e005989db37c26fd13bb6d2fab2" 14459f8]:
{{{
#!CommitTicketReference repository=""
revision="14459f80ee3a9e005989db37c26fd13bb6d2fab2"
Fixed #34140 -- Reformatted code blocks in docs with blacken-docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"32f224e359c68e70e3f9a230be0265dcd6677079" 32f224e]:
{{{
#!CommitTicketReference repository=""
revision="32f224e359c68e70e3f9a230be0265dcd6677079"
[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 <smi...@gmail.com>
Backport of 6015bab80e28aef2669f6fac53423aa65f70cb08 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:17>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"62510f01e76ad0526c94ea6d1bc6399c1ddf3df4" 62510f0]:
{{{
#!CommitTicketReference repository=""
revision="62510f01e76ad0526c94ea6d1bc6399c1ddf3df4"
[4.2.x] Fixed #34140 -- Reformatted code blocks in docs with blacken-docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:18>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"8d2ac000e43c1cfa3d331a1580525ead3d5f32d7" 8d2ac000]:
{{{
#!CommitTicketReference repository=""
revision="8d2ac000e43c1cfa3d331a1580525ead3d5f32d7"
[4.2.x] Refs #34140 -- Made minor edits to rst code-blocks.
Backport of 9cf2a5df70051dffcefe21c6b27203e2d5804922 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:16>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by GitHub <noreply@…>):
In [changeset:"d89a465e62ad876cc7f1332d1712700cb81f3995" d89a465e]:
{{{
#!CommitTicketReference repository=""
revision="d89a465e62ad876cc7f1332d1712700cb81f3995"
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.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:19>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
In [changeset:"45fae65672e7a1133c378416cfeb4c9af285ab88" 45fae656]:
{{{#!CommitTicketReference repository=""
revision="45fae65672e7a1133c378416cfeb4c9af285ab88"
[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
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:20>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
In [changeset:"cba73281966c816824c9bfa028a1bf44e188ded2" cba7328]:
{{{#!CommitTicketReference repository=""
revision="cba73281966c816824c9bfa028a1bf44e188ded2"
Refs #34140 -- Added dedicated code block formatting section in
docs/internals/contributing/writing-documentation.txt.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:21>
Django
-------------------------------------+-------------------------------------
Reporter: Paolo Melchiorre | Owner: Joseph V
Type: | Zammit
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
format,black,snippet,example |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
In [changeset:"5ad6d43cd9ae05d3575f9e7bb1cb488bce5d905d" 5ad6d43]:
{{{#!CommitTicketReference repository=""
revision="5ad6d43cd9ae05d3575f9e7bb1cb488bce5d905d"
[5.2.x] Refs #34140 -- Added dedicated code block formatting section in
docs/internals/contributing/writing-documentation.txt.
Backport of cba73281966c816824c9bfa028a1bf44e188ded2 from main.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/34140#comment:22>