Skip to content

Docs: Mentioned doctest formatting (Closes #3083)#4908

Closed
SnippyCodes wants to merge 4 commits into
psf:mainfrom
SnippyCodes:fix/issue-3083-doctest
Closed

Docs: Mentioned doctest formatting (Closes #3083)#4908
SnippyCodes wants to merge 4 commits into
psf:mainfrom
SnippyCodes:fix/issue-3083-doctest

Conversation

@SnippyCodes
Copy link
Copy Markdown

@SnippyCodes SnippyCodes commented Dec 12, 2025

Description

This Pull Request addresses Issue #3083 by updating the documentation to mention third-party tools that can be used to format code examples embedded in docstrings (doctests).

Since Black does not format doctests by default, this documentation clarifies for users how to achieve consistent formatting across their entire project.

I have added a new section, "Formatting Doctests," to docs/usage_and_configuration/the_basics.md, recommending the use of the blacken-docs tool.

Closes #3083

Checklist - did you ...

  • Implement any code style changes under the --preview style, following the
    stability policy?
  • Add an entry in CHANGES.md if necessary?
  • Add / update tests if necessary?
  • Add new / update outdated documentation?

@SnippyCodes SnippyCodes force-pushed the fix/issue-3083-doctest branch from c9b3b6b to 3815733 Compare December 17, 2025 13:38
@cobaltt7
Copy link
Copy Markdown
Collaborator

This PR has some issues. Most notably, blacken-docs does not exist.

I'm inclined to believe that this PR is AI-generated. While using AI in itself isn't forbidden, we do expect you to look over what the AI did, that you've reviewed the code it writes, and that submitted PRs are up to our code standards and in line with the project expectations and requirements. Unfortunately, your contribution does not meet this bar.

We don't have the resources to review AI-generated PRs, which are often of low quality. If you aren't already aware:

  • AIs often hallucinate, i.e. lie and make stuff up.
  • AI does understand subtle context. While its output may be factually correct, it is likely that it is irrelevant/inapplicable to the exact situation because of unknown requirements, missing knowledge, etc.
  • AI generated texts are also generally hard and tiring to read. AI often generates walls of text that are full of fluff and redundant statements.

Again, you can use AIs as part of your work, but you are responsible for verifying their output and that they do not impact others' ability to contribute productively.

Thank you for your understanding.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation: mention tools that can do doctests formatting

2 participants