Some minor clarifications in the documentation of pathlib + inheritance diagram

Doc/library/pathlib.rst

@@ -9,15 +9,27 @@
 
 .. versionadded:: 3.4
 
-
 This module offers classes representing filesystem paths with semantics
 appropriate for different operating systems.  Path classes are divided
 between :ref:`pure paths <pure-paths>`, which provide purely computational
 operations without I/O, and :ref:`concrete paths <concrete-paths>`, which
 inherit from pure paths but also provide I/O operations.
 
-The main point of entry is the :class:`Path` class, which will instantiate
+.. image:: pathlib-inheritance.png
-a :ref:`concrete path <concrete-paths>` for the current platform.
+   :align: center
+
+If you've never used this module before or just aren't sure which class is
+right for your task, :class:`Path` is most likely what you need. It instantiates
+a :ref:`concrete path <concrete-paths>` for the platform the code is running on.
+
+Pure paths are useful in some special cases; for example:
+
+#. If you want to manipulate Windows paths on a Unix machine (or vice versa).
+   You cannot instantiate a :class:`WindowsPath` when running on Unix, but you
+   can instantiate :class:`PureWindowsPath`.
+#. You want to make sure that your code only manipulates paths without actually
+   accessing the OS. In this case, instantiating one of the pure classes may be
+   useful since those simply don't have any OS-accessing operations.
 
 .. note::
    This module has been included in the standard library on a
@@ -86,54 +98,27 @@ Pure path objects provide path-handling operations which don't actually
 access a filesystem.  There are three ways to access these classes, which
 we also call *flavours*:
 
-
+.. class:: PurePath(*pathsegments)
-.. class:: PurePosixPath
-
-   A subclass of :class:`PurePath`, this path flavour represents non-Windows
-   filesystem paths::
-
-      >>> PurePosixPath('/etc')
-      PurePosixPath('/etc')
-
-.. class:: PureWindowsPath
-
-   A subclass of :class:`PurePath`, this path flavour represents Windows
-   filesystem paths::
-
-      >>> PureWindowsPath('c:/Program Files/')
-      PureWindowsPath('c:/Program Files')
-
-.. class:: PurePath
 
    A generic class that represents the system's path flavour (instantiating
    it creates either a :class:`PurePosixPath` or a :class:`PureWindowsPath`)::
 
-      >>> PurePath('setup.py')
+      >>> PurePath('setup.py')      # Running on a Unix machine
       PurePosixPath('setup.py')
 
-
+   Each element of *pathsegments* can be either a string or bytes object
-Regardless of the system you're running on, you can instantiate all of
+   representing a path segment; it can also be another path object::
-these classes, since they don't provide any operation that does system calls.
-
-
-Constructing paths
-^^^^^^^^^^^^^^^^^^
-
-Path constructors accept an arbitrary number of positional arguments.
-When called without any argument, a path object points to the current
-directory::
-
-   >>> PurePath()
-   PurePosixPath('.')
-
-Any argument can be a string or bytes object representing an arbitrary number
-of path segments, but it can also be another path object::
 
       >>> PurePath('foo', 'some/path', 'bar')
       PurePosixPath('foo/some/path/bar')
       >>> PurePath(Path('foo'), Path('bar'))
       PurePosixPath('foo/bar')
 
+   When *pathsegments* is empty, the current directory is assumed::
+
+      >>> PurePath()
+      PurePosixPath('.')
+
    When several absolute paths are given, the last is taken as an anchor
    (mimicking :func:`os.path.join`'s behaviour)::
 
@@ -163,6 +148,29 @@ symbolic links::
    to ``PurePosixPath('bar')``, which is wrong if ``foo`` is a symbolic link
    to another directory)
 
+.. class:: PurePosixPath(*pathsegments)
+
+   A subclass of :class:`PurePath`, this path flavour represents non-Windows
+   filesystem paths::
+
+      >>> PurePosixPath('/etc')
+      PurePosixPath('/etc')
+
+   *pathsegments* is specified similarly to :class:`PurePath`.
+
+.. class:: PureWindowsPath(*pathsegments)
+
+   A subclass of :class:`PurePath`, this path flavour represents Windows
+   filesystem paths::
+
+      >>> PureWindowsPath('c:/Program Files/')
+      PureWindowsPath('c:/Program Files')
+
+   *pathsegments* is specified similarly to :class:`PurePath`.
+
+Regardless of the system you're running on, you can instantiate all of
+these classes, since they don't provide any operation that does system calls.
+
 
 General properties
 ^^^^^^^^^^^^^^^^^^
@@ -524,24 +532,7 @@ Concrete paths are subclasses of the pure path classes.  In addition to
 operations provided by the latter, they also provide methods to do system
 calls on path objects.  There are three ways to instantiate concrete paths:
 
-
+.. class:: Path(*pathsegments)
-.. class:: PosixPath
-
-   A subclass of :class:`Path` and :class:`PurePosixPath`, this class
-   represents concrete non-Windows filesystem paths::
-
-      >>> PosixPath('/etc')
-      PosixPath('/etc')
-
-.. class:: WindowsPath
-
-   A subclass of :class:`Path` and :class:`PureWindowsPath`, this class
-   represents concrete Windows filesystem paths::
-
-      >>> WindowsPath('c:/Program Files/')
-      WindowsPath('c:/Program Files')
-
-.. class:: Path
 
    A subclass of :class:`PurePath`, this class represents concrete paths of
    the system's path flavour (instantiating it creates either a
@@ -550,6 +541,27 @@ calls on path objects.  There are three ways to instantiate concrete paths:
       >>> Path('setup.py')
       PosixPath('setup.py')
 
+   *pathsegments* is specified similarly to :class:`PurePath`.
+
+.. class:: PosixPath(*pathsegments)
+
+   A subclass of :class:`Path` and :class:`PurePosixPath`, this class
+   represents concrete non-Windows filesystem paths::
+
+      >>> PosixPath('/etc')
+      PosixPath('/etc')
+
+   *pathsegments* is specified similarly to :class:`PurePath`.
+
+.. class:: WindowsPath(*pathsegments)
+
+   A subclass of :class:`Path` and :class:`PureWindowsPath`, this class
+   represents concrete Windows filesystem paths::
+
+      >>> WindowsPath('c:/Program Files/')
+      WindowsPath('c:/Program Files')
+
+   *pathsegments* is specified similarly to :class:`PurePath`.
 
 You can only instantiate the class flavour that corresponds to your system
 (allowing system calls on non-compatible path flavours could lead to