Skip to content

glob module docs in wrong order #110417

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
barneygale opened this issue Oct 5, 2023 · 2 comments
Closed

glob module docs in wrong order #110417

barneygale opened this issue Oct 5, 2023 · 2 comments
Labels
docs Documentation in the Doc dir

Comments

@barneygale
Copy link
Contributor

barneygale commented Oct 5, 2023 •
edited by bedevere-app bot
Loading

The documentation of the glob module is in a slightly odd order:

  1. A description of the globbing language (wildcards etc)
  2. A "see also: pathlib" block
  3. Function documentation:
    a. glob()
    b. iglob()
    c. escape()
  4. Two examples of using glob()
  5. A "see also: fnmatch" block

In particular, the description of glob() and the examples of its usage are interrupted by descriptions of iglob() and escape().

I think this might be better:

  1. A description of the globbing language (wildcards etc)
  2. A "see also: fnmatch" block
  3. A "see also: pathlib" block
  4. Function documentation:
    a. glob(), including two examples of its usage
    b. iglob()
    c. escape()

Linked PRs
@barneygale barneygale added the docs Documentation in the Doc dir label Oct 5, 2023
barneygale added a commit to barneygale/cpython that referenced this issue Oct 5, 2023
@barneygale
pythonGH-110417: Improve ordering of info in glob docs
b0c57e8 
Move examples of `glob()` usage into the `.. function:: glob()` block, and
move the mention of `fnmatch` to just before the mention of `pathlib`.

As a result, the description and examples of `glob()` are not interrupted
by descriptions of `iglob()` and `escape()`.
@bedevere-app bedevere-app bot mentioned this issue Oct 5, 2023
Merged
barneygale added a commit to barneygale/cpython that referenced this issue Nov 13, 2023
@barneygale
Merge branch 'main' into pythongh-110417-glob-docs-ordering
e0904dc
barneygale added a commit that referenced this issue Nov 13, 2023
@barneygale
GH-110417: Fix glob docs ordering (#110418)
d5491a6 
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()`.
@terryjreedy
Copy link
Member

Why not backport? Conflicts from changes?

@barneygale
Copy link
Contributor Author

barneygale commented Nov 13, 2023 •
edited
Loading

Conflicts, and the changes in 3.12 and prior seem to minor to be worth it I think.

I can backport if you think it's worthwhile?

aisk pushed a commit to aisk/cpython that referenced this issue Feb 11, 2024
@barneygale @aisk
pythonGH-110417: Fix glob docs ordering (python#110418)
274b472 
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()`.
Glyphack pushed a commit to Glyphack/cpython that referenced this issue Sep 2, 2024
@barneygale @Glyphack
pythonGH-110417: Fix glob docs ordering (python#110418)
83924a4 
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()`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@barneygale @terryjreedy