GH-110417: Fix glob docs ordering

[barneygale]

Fix placement of translate() docs.

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().

• Issue: glob module docs in wrong order #110417

---

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

[barneygale]

Maybe the "See also" bits would be better at the end? Hm.

[ezio-melotti]

I'm not sure I agree with this reordering. Having the examples at the bottom of the page is a common pattern used by several other pages, however most other pages are a bit more structured, with clear headers to separate different sections.

In this case, even thought the examples only use glob, they might as well work for iglob (and I think this was the original intent, before the addition of escape). If someone follows a direct link to iglob, they might miss these examples now that they are in glob. On the other hand, someone reading glob docs might not notice that there are examples at the bottom (this is a side-effect of having examples at the bottom of the page).

Since this specific page is quite short, I think it might be ok to leave the examples at the bottom, and add headers to make the sections stand out more. Adding links to the examples within the function description is probably not necessary.

By doing this we can also maintain a diataxian separation of the 3 different parts:

• the initial description (explanation)
• the list of functions (reference)
• the examples (howto)

[erlend-aasland]

Since this specific page is quite short, I think it might be ok to leave the examples at the bottom, and add headers to make the sections stand out more. Adding links to the examples within the function description is probably not necessary.

I think this is a good idea. You can link to the examples (or how-tos, or guides ...) from the reference. OTOH, it is ok to include short examples in the reference, iff they are specific to the API they are describing.

[gvanrossum]

Thank you!

[barneygale]

Thank you very much for the explanation and pointers @ezio-melotti and @erlend-aasland! I think I understand now.

I've revised the PR so that the examples stay put. Instead:

• The "see also: pathlib" bit is moved to the end (alongside "see also: fnmatch")
• The function definitions are introduced by a "This module defines these functions:" sentence, which seems to be a common formulation in other module docs. Perhaps this is pointless; happy to take it out.
• The examples are preceded by a new "Examples" subheading, and the introductory wording very slightly revised.

I couldn't really find other examples of a simple "Functions" subheading. Do you think the "Examples" subheading alone works? I think it reads pretty well now: https://cpython-previews--110418.org.readthedocs.build/en/110418/library/glob.html

Also happy to withdraw this PR entirely if we think there's nothing worth doing here.