Doc: Summary table for pathlib

[Nodd]

In the same vein as #125810, this PR adds a table summary to the pathlib module documentation. It helps to view all the available attributes and methods at a glance.

See also the discussion on Discourse

Direct link to the modified pathlib documentation

---

📚 Documentation preview 📚: https://cpython-previews--126342.org.readthedocs.build/

[nedbat]

Thanks for doing the work to create these tables. Concrete examples are much better for discussion. When I look at this table, I find the repeated class names distracting and obscuring the thing I want to see, the method names. I'd love to find a way to let the method names stand out more. I doubt rst could make them bold.

[Nodd]

It doesn't look like it's possible: https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible. I tried just in case, but it really doesn't work. The workaround proposed would not be realistically maintainable, and I can't make it work for internal links:

Here is an |Path.lchmod|_.

.. |Path.lchmod| replace:: Path.\ **lchmod**\ (mode)
.. _Path.lchmod: :meth:`Path.lchmod`

renders as

but the link is wrong, it points to file:///home/joseph/Programmation/Python/cpython.git/Doc/build/html/library/:meth:%60Path.lchmod%60

I could remove the class name completely, but it would become misleading. Also, the distinction between PurePath and Path can be important.

[hugovk]

The table is struggling to fit on mobile, likely due to some long entries with no spaces for it to break on like PurePath.with_segments(*pathsegments):

Details

We could adjust CSS to use something like overflow-wrap: anywhere (instead of overflow-wrap: break-word), but I'm not keen on that:

Details

Or dropping class names would help. Here's just one removed here, shall we try with more?

Details

I also recommend using reST's list-table for tables, it's much less of a pain that monkeying around with whitespace for the ASCII layout:

https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html#list-table-directive

[Nodd]

I'd prefer list-tables too, but AFAIK it's not possible to span cells over multiple columns like I do for the section titles. I tried to use multiple tables in the math module, but it didn't look good at all on PC.

I'm afraid that completely dropping class names might be confusing. I would like to have similar tables in many module documentations, and it wouldn't play well if there are both methods and functions in a module. How about using P instead of Path and PP instead of PurePath in the table? This way the names are shorter, but are still explicitly marked as methods. I can add a paragraph just before the table to explain the notation.

[Nodd]

To answer @nedbat's comment, one way to make the method names stand out is to put the link on the method only, and not the class. I did an example using the PP shortcut but it would work with the full name too. It works, but since it's not the standard used elsewhere, it looks a bit weird.

Another format can be used for the "PP." part:

[treyhunner]

This pathlib summary table seems like a great addition and I am excited to see these summary tables being added to the Python documentation.

I'm afraid that completely dropping class names might be confusing. I would like to have similar tables in many module documentations, and it wouldn't play well if there are both methods and functions in a module. How about using P instead of Path and PP instead of PurePath in the table? This way the names are shorter, but are still explicitly marked as methods. I can add a paragraph just before the table to explain the notation.

How about p? My students sometimes see str.lower in documentation and reach for str.lower(my_string) rather than my_string.lower(). Showing a lowercase p variable that looks like a variable pointing to a pathlib.Path object might help reduce confusion on how to call the methods as well.

Changing pathsegments to segments also seems to help.

Putting a <wbr> tag after the ( in method calls may help also. I'm not sure whether there would be an easy way to systematize that without doing it manually for each long "word" (e.g. PureWindowsPath(*segments) to PureWindowsPath(<wbr>*segments)).

[Nodd]

How about p?

Here is what it looks like with p:

Changing pathsegments to segments also seems to help.

I'd prefer to keep the same signature in the table and for the function, to avoid confusion for both the reader and future doc maintainers.

Putting a <wbr> tag after the ( in method calls may help also.

<wbr> is a great idea, but it doesn't seem to work as it clashes with the link syntax. I tried to use a substitution but it didn't work either. What work is using the unicode character ZERO WIDTH SPACE, but inserting invisible spaces in the RST code seems a bad idea!

[Nodd]

I also recommend using reST's list-table for tables, it's much less of a pain that monkeying around with whitespace for the ASCII layout:

https://sublime-and-sphinx-guide.readthedocs.io/en/latest/tables.html#list-table-directive

We could use flat-table, but it's an external sphinx extension that would add a new dependency. As a newcomer, I don't know if it's worth it.

[hugovk]

We could use flat-table, but it's an external sphinx extension that would add a new dependency. As a newcomer, I don't know if it's worth it.

We generally avoid using external extensions, as downstream redistributors often build without them.

[barneygale]

Thanks for putting this together. I'm a little uneasy about the table needing to be manually maintained, when other documentation tools (I'm thinking of Doxygen) can automatically create these summary tables. But I don't know too much about CPython docs practices, so if others are fine with it, then I am too.

[Nodd]

Initially I had the same thought. I tried to play with autosummary, but I couldn't make it work, I don't know why. I abandoned the idea because that would pull the documentation from the docstrings, while the rest of the documentation in the RST files is independent, as far as I know. The initial tables are indeed tedious to write, but all the python documentation is actually written by hand, independently of the code.