gh-115986: Use param list to mark up pprint.PrettyPrinter constructor

[erlend-aasland]

• Issue: Improve documentation for pprint module #115986

---

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

[erlend-aasland]

cc. @Privat33r-dev

[Privat33r-dev]

Side note:

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 above.

Just noticed 2 documentation above mentions, which is inaccurate after we moved class to the bottom.

[Privat33r-dev]

Maybe a passive tense would be more accurate choice? will be displayed. Though I am not sure.

[erlend-aasland]

Just noticed 2 documentation above mentions, which is inaccurate after we moved class to the bottom.

Good catch. Can you please open a PR to fix that?

[AlexWaygood]

I think the fundamental problem with this module's docs is that they've been written by somebody thinking about it from the perspective of how the module is implemented, rather than from the perspective of how users generally use it. From the perspective of the implementation, it makes sense to document the meaning of all these parameters as part of the PrettyPrinter class, since all the module-level functions are just abstractions over that class. But from the perspective of the user, I'm not sure that really makes sense — users of this module rarely need to use the low-level class.

So maybe the meaning of these parameters should be documented in a separate table somewhere in these docs, rather than as part of the documentation of this class — we could just say the parameters have the same meaning for all functions in the module

[Privat33r-dev]

So maybe the meaning of these parameters should be documented in a separate table somewhere in these docs, rather than as part of the documentation of this class — we could just say the parameters have the same meaning for all functions in the module

Is there an example of this style? I would definitely agree that we should make params for pprint functions more visible.

[Privat33r-dev]

Good catch. Can you please open a PR to fix that?

#116104

[AlexWaygood]

Is there an example of this style?

I'm imagining a table that looks a bit like https://docs.python.org/3/library/typing.html#id7 (source code at

cpython/Doc/library/typing.rst

Line 2736 in 86e5e06

.. list-table:: **Recognised parameters for field specifiers**

)

[erlend-aasland]

I agree, @AlexWaygood. We ran into similar problems in the ftplib docs. Perhaps we should consider this approach over there as well.

I'll close this PR for now.

[Privat33r-dev]

Is there an example of this style?

I'm imagining a table that looks a bit like https://docs.python.org/3/library/typing.html#id7 (source code at

cpython/Doc/library/typing.rst

Line 2736 in 86e5e06

.. list-table:: **Recognised parameters for field specifiers**

)

I wish there was a more modern design for the table though. I am not sure where I can post proposal for it, but it would be nice if instead of this:

It looked at least like this:

[erlend-aasland]

@Privat33r-dev, I'd try and ask in the Documentation category on Discourse, or on our Python Docs Discord server.