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 more documentation about preview style features #4429

Open
AshSta512 opened this issue Aug 6, 2024 · 2 comments
Open

Add more documentation about preview style features #4429

AshSta512 opened this issue Aug 6, 2024 · 2 comments
Labels
T: documentation Improvements to the docs (e.g. new topic, correction, etc)

Comments

@AshSta512
Copy link

Is this related to a problem? Please describe.

The descriptions of many preview style features aren't very descriptive as they only have one sentence explaining each of them in the docs.
This can lead to uncertainty about how some of the preview features affect formatting.
Contrasting this to the unstable style features that have dedicated sections and examples explaining what they do, I feel that the preview style features should receive the same treatment.

Describe the solution you'd like

Similar to the unstable style features, I would like to see a dedicated section for each preview style feature that includes a more descriptive explanation alongside one or more code examples.

The sections for each feature don't have to be long to avoid bloating the documentation, but I feel more than the single sentence description would help users to understand how the preview style affects their code.

Describe alternatives you've considered

An alternative to dedicated sections could be to simply add more clarity to the existing descriptions through offering a few sentences per feature and/or an example for the features that aren't as obvious.

@AshSta512 AshSta512 added the T: documentation Improvements to the docs (e.g. new topic, correction, etc) label Aug 6, 2024
@datasharp
Copy link

I'd like to be assigned this issue.
My plan is to add some sections as described above where I can show some examples for different styles. The sections would be very short, just a few sentences per feature as described above.

@JelleZijlstra
Copy link
Collaborator

We don't generally assign issues, but contributions are welcome! Looks like with the recent release of the 2025 stable style, there's only one undocumented preview feature (always_one_newline_after_import).

Nativ-Thousandyear added a commit to WSU-CptS-581-2025/black_code_formatter that referenced this issue Mar 2, 2025
psf#4429 issue addressed. Update preview features (preview style feature: always_one_newline_after_import)
Nativ-Thousandyear added a commit to WSU-CptS-581-2025/black_code_formatter that referenced this issue Mar 2, 2025
psf#4429 issue address: updated "add new line after imports" preview style features update (examples added to documentation).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
T: documentation Improvements to the docs (e.g. new topic, correction, etc)
Projects
None yet
Development

No branches or pull requests

3 participants