Fix minor docstring issues in dataclasses.py

[romanngg]

Fix minor docstring issues in dataclasses.py.

Otherwise, when using functools.wrap around them (and inherit their docstrings), sphinx renders the docstrings badly and raises warnings about wrong indent.

[ghost]

All commit authors signed the Contributor License Agreement.

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[ericvsmith]

I don’t know a lot about sphinx (clearly). Could you walk me through a few steps on how I can verify the previous behavior was wrong, and this PR fixes the issue? Thanks.

[AA-Turner]

@ericvsmith this is more a reStructuredText issue than a Sphinx one -- the double colon marks the start of an (indented) code block, and the other changes seem alright in terms of ensuring that consistency of indentation is correct within the same code-block.

As for testing, perhaps @romangg is using Sphinx's autodoc or something similar, which renders the docstring as reStructuredText?

A

[romanngg]

Thanks @AA-Turner that's exactly what I'm doing! @ericvsmith in terms of verifying I can suggest the following steps (also newbie here, haven't figured out a simpler way to repro):

1. pip install sphinx
2. In some directory make an index.rst file containing

.. automodule:: dataclasses
   :members:

and a conf.py file with

extensions = ['sphinx.ext.autodoc',]

3. In that directory run sphinx-build . _build

Without the changes above, you will see warnings like

romann@romann2 ~/autodoc_test> sphinx-build . _build                                                                                                                                                                                   (base) 
Running Sphinx v4.2.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] index                                                                                                                                                                                                               
/usr/local/google/home/romann/anaconda3/lib/python3.9/dataclasses.py:docstring of dataclasses.asdict:8: WARNING: Unexpected indentation.
/usr/local/google/home/romann/anaconda3/lib/python3.9/dataclasses.py:docstring of dataclasses.make_dataclass:14: WARNING: Unexpected indentation.
/usr/local/google/home/romann/anaconda3/lib/python3.9/dataclasses.py:docstring of dataclasses.replace:7: WARNING: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                                                                
generating indices... genindex py-modindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 3 warnings.

The HTML pages are in _build.

And the _build/index.html will render some code blocks as regular text. After the changes there are no warnings, and the rendering works correctly, let me know if this works!

[ericvsmith]

It turns out I'm too busy or lazy to test this with Sphinx, but the changes don't look unreasonable and can always be reverted.

GH is complaining about tests not passing, so I'm going to close then re-open this. I'm not sure if we'll need to update the PR branch or not, we'll see.

[miss-islington]

Thanks @romanngg for the PR, and @ericvsmith for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-95286 is a backport of this pull request to the 3.11 branch.