From d5491a6eff516ad47906bd91a13d71cdde18f5ab Mon Sep 17 00:00:00 2001
From: Barney Gale <barney.gale@gmail.com>
Date: Mon, 13 Nov 2023 17:48:16 +0000
Subject: 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()`.
---
 Doc/library/glob.rst | 69 ++++++++++++++++++++++++++--------------------------
 1 file changed, 35 insertions(+), 34 deletions(-)

diff --git a/Doc/library/glob.rst b/Doc/library/glob.rst
index 8e76d2d..6e4f72c 100644
--- 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.
-- 
cgit v0.12