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

barneygale · web-flow · commit d5491a6eff51 · 2023-11-13T17:48:16.000Z
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
@@ -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.
