gh-115986 Improve pprint docs formatting

[Privat33r-dev]

The change improves readability.
Suggested in the #116085 PR discussion.

• Issue: Improve documentation for pprint module #115986

---

📚 Documentation preview 📚: https://cpython-previews--117401.org.readthedocs.build/en/117401/library/pprint.html

[erlend-aasland]

If we're putting the params list in the pprint.pprint function docs, we could just as well use the standardised Sphinx param list markup (:param:, :type:, etc.). We'll probably refer to pprint.pprint from the pprint.pp and the PrettyPrinter docs anyway, so using the standard markup seems like a better way to me. cc. @AlexWaygood @hugovk

[Privat33r-dev]

@erlend-aasland, I do completely agree that :param: will look better, especially considering the fact that we want to keep parameters' types as well and :param: look much more suitable for this purpose. I was hesitant to express my opinion earlier as everyone seemed to agree on table's solution, but now I see that it made more sense to speak my mind.

Moreover, I want to address the whole "pp vs pprint" thing. If we are writing docs from the developer's perspective, it would seem more logical to write the full description in one function's docs and just mention in another that it's an alias to keep everything DRY and readable (please, ignore formatting and minor details):

pprint.pp(object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=False, underscore_numbers=False)
Prints the formatted representation of object on stream, followed by a newline. If stream is None, [sys.stdout] is used. This may be used in the interactive interpreter instead of the [print()] function for inspecting values (you can even reassign print = pprint.pp for use within a scope).

The configuration parameters stream, indent, width, depth, compact, sort_dicts and underscore_numbers are passed to the [PrettyPrinter] constructor and their meanings are as described in its documentation below.

** PrettyPrinter PARAMS HERE **

pprint.pprint(object, stream=None, indent=1, width=80, depth=None, *, compact=False, sort_dicts=True, underscore_numbers=False)
Alias to pprint.pp. Note that sort_dicts is True by default and you might want to use [pp()] instead where it is False by default.

It feels like it would make the most sense, because here we would give all the usage info on pprint.pp and only then mention "pprint.pprint" and other stuff.

[erlend-aasland]

@Privat33r-dev, do you have a draft PR of your suggestion?

[Privat33r-dev]

@Privat33r-dev, do you have a draft PR of your suggestion?

not yet, but I can make (or rather edit existing) one if my proposed change sounds good

[erlend-aasland]

not yet, but I can make (or rather edit existing) one if my proposed change sounds good

I think a draft PR would be interesting, but only if you have time available for it; I find it easier to decide on doc layouts when they are rendered :)

[Privat33r-dev]

not yet, but I can make (or rather edit existing) one if my proposed change sounds good

I think a draft PR would be interesting, but only if you have time available for it; I find it easier to decide on doc layouts when they are rendered :)

done, you can check it out :)

[erlend-aasland]

Thanks! I like this very much. We could use Sphinx placeholders to minimise the duplication. I'm not sure if it is worth it, though, because you'd have to create one placeholder for each parameter description.

[Privat33r-dev]

There are 2 differences between the params table:

1. "object" presence as the first param
2. (the default) placement for sort_dicts param

Even if we technically can make a placeholder for table (by "table" I mean params list), the first difference is resolved by putting :param: before the table, but the second difference could be resolved only by moving the table to pprint.pprint or by somehow replacing the content of the placeholder (which is kind of hacky).

We can keep it DAMP for now since there is low change of significant changes in the pprint.pprint and in case if there are some changes (which will unlikely involve parameters), we can add comment to rst that edit should be made twice.

[Privat33r-dev]

My recent change
Move code out of parameter

Screenshots

Before

After

Move code out of "changed in version" and move the latter down

Screenshots

Before

After

[erlend-aasland]

Moving the example code out of the parameter list sounds good. IMO we should never embed code examples in parameter lists, since it is (IMO) visually cluttering.

[Privat33r-dev]

Moving the example code out of the parameter list sounds good. IMO we should never embed code examples in parameter lists, since it is (IMO) visually cluttering.

Moving example code in the param was unintentional consequence of adding params :)

I am not sure how to fix the tests though. Can you give an advise? This change will likely do the trick:

But I'd prefer to keep the indentation and avoid "usage example" and similar things to keep the document's consistency.

[erlend-aasland]

I am not sure how to fix the tests though

You need to adjust the indentation so it matches the expected output; AFAIK, there is no other way.

[Privat33r-dev]

I am not sure how to fix the tests though

You need to adjust the indentation so it matches the expected output; AFAIK, there is no other way.

putting additional newline between "usage example" and code fixed the indentation. I tried to use comment (.. example\n\n{code}), but it made example visually disappear (since I guess the code become child of comment). I guess we go with "usage example"s now. But, I guess, it makes the doc more explicit now :)

[Privat33r-dev]

I figured out that the problem wasn't in the indentation of the code block but because my IDE decided to align code inside of the code blocks on <shift>+<tab>.

[Privat33r-dev]

Well, after watching the Steven He's "Failure Management" course, I can confidently say that the problem is still in indentation and reducing amount of failures from 3 to 1 is a partial success.

[Privat33r-dev]

Failure has been successfully managed. Ready for review :)

P.S. Why does doctest job take 16 minutes? Diving a bit deeper I noticed that doctest.py does not parallelize jobs, it might be the problem.