GH-110417: Fix `glob` docs ordering (#110418)

Fix incorrect placement of `translate()` docs from cf67ebf.

Move "see also: pathlib" admonition to the bottom of the page, alongside one for fnmatch. This helps the module introduction flow more naturally into the function descriptions.

Add an "Examples" subheading just before the examples. This makes it more obvious that examples aren't specifically related to the preceding documentation of `escape()` and `translate()`.

diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst
index 8e76d2d5f1653591fcd99480bea05323399b4f1e..6e4f72c19ff4c97e3629b3d669d783519ab86fe9 100644 (file)
--- a/Doc/library/glob.rst
+++ b/Doc/library/glob.rst
@@ -34,9 +34,7 @@ unlike :func:`fnmatch.fnmatch` or :func:`pathlib.Path.glob`.
 For a literal match, wrap the meta-characters in brackets.
 For example, ``'[?]'`` matches the character ``'?'``.
 
-
-.. seealso::
-   The :mod:`pathlib` module offers high-level path objects.
+The :mod:`glob` module defines the following functions:
 
 
 .. function:: glob(pathname, *, root_dir=None, dir_fd=None, recursive=False, \
@@ -117,35 +115,6 @@ For example, ``'[?]'`` matches the character ``'?'``.
    .. versionadded:: 3.4
 
 
-For example, consider a directory containing the following files:
-:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub`
-which contains only the file :file:`3.txt`.  :func:`glob` will produce
-the following results.  Notice how any leading components of the path are
-preserved. ::
-
-   >>> import glob
-   >>> glob.glob('./[0-9].*')
-   ['./1.gif', './2.txt']
-   >>> glob.glob('*.gif')
-   ['1.gif', 'card.gif']
-   >>> glob.glob('?.gif')
-   ['1.gif']
-   >>> glob.glob('**/*.txt', recursive=True)
-   ['2.txt', 'sub/3.txt']
-   >>> glob.glob('./**/', recursive=True)
-   ['./', './sub/']
-
-If the directory contains files starting with ``.`` they won't be matched by
-default. For example, consider a directory containing :file:`card.gif` and
-:file:`.card.gif`::
-
-   >>> import glob
-   >>> glob.glob('*.gif')
-   ['card.gif']
-   >>> glob.glob('.c*')
-   ['.card.gif']
-
-
 .. function:: translate(pathname, *, recursive=False, include_hidden=False, seps=None)
 
    Convert the given path specification to a regular expression for use with
@@ -184,7 +153,39 @@ default. For example, consider a directory containing :file:`card.gif` and
    .. versionadded:: 3.13
 
 
+Examples
+--------
+
+Consider a directory containing the following files:
+:file:`1.gif`, :file:`2.txt`, :file:`card.gif` and a subdirectory :file:`sub`
+which contains only the file :file:`3.txt`.  :func:`glob` will produce
+the following results.  Notice how any leading components of the path are
+preserved. ::
+
+   >>> import glob
+   >>> glob.glob('./[0-9].*')
+   ['./1.gif', './2.txt']
+   >>> glob.glob('*.gif')
+   ['1.gif', 'card.gif']
+   >>> glob.glob('?.gif')
+   ['1.gif']
+   >>> glob.glob('**/*.txt', recursive=True)
+   ['2.txt', 'sub/3.txt']
+   >>> glob.glob('./**/', recursive=True)
+   ['./', './sub/']
+
+If the directory contains files starting with ``.`` they won't be matched by
+default. For example, consider a directory containing :file:`card.gif` and
+:file:`.card.gif`::
+
+   >>> import glob
+   >>> glob.glob('*.gif')
+   ['card.gif']
+   >>> glob.glob('.c*')
+   ['.card.gif']
+
 .. seealso::
+   The :mod:`fnmatch` module offers shell-style filename (not path) expansion.
 
-   Module :mod:`fnmatch`
-      Shell-style filename (not path) expansion
+.. seealso::
+   The :mod:`pathlib` module offers high-level path objects.