Skip to content

GH-56426: Add cross-reference to the documentation for faulthandler, traceback, and pdb. #101157

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.

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

Merged
merged 7 commits into from
Feb 4, 2023

Conversation

furkanonder
Copy link
Contributor

@furkanonder furkanonder commented Jan 19, 2023

Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general, and as seems to be typically done in practice, from what I've seen, module-level see-alsos are usually work best near the beginning of the doc, at the end of the module-level summary/description and before the first section, function, classes, methods, etc, rather than buried at the end. This keeps them in the same place as the other module-level information, rather than part of an unrelated section, and makes it much easy for readers to find other related modules that might suit their use case better without having to read through the entire module doc first.

Also, a couple suggestions.

furkanonder and others added 3 commits January 20, 2023 11:42
@CAM-Gerlach
Copy link
Member

More specifically, I suggest moving the See-Also block in...

  • faulthandler.rst to line 45, after the top-level module description
  • pdb.rst to line 29, after the top-level module description paragraphs but before the detailed example (or perhaps line 98, at the end of the top level description and before the API docs, but it's a little buried there)
  • traceback.rst to line 22, after the top-level module description

Thanks!

@furkanonder
Copy link
Contributor Author

More specifically, I suggest moving the See-Also block in...

* `faulthandler.rst` to line 45, after the top-level module description

* `pdb.rst` to line 29, after the top-level module description paragraphs but before the detailed example (or perhaps line 98, at the end of the top level description and before the API docs, but it's a little buried there)

* `traceback.rst` to line 22, after the top-level module description

Thanks!

I went over the pickle and reg module documentation, adding a see also section. Sections were added below the documents. I completely agree that see-also section at the beginning of the document would be more useful and attention-grabbing. Thank you very much for your assistance and line-by-line explanation !

@furkanonder furkanonder requested review from CAM-Gerlach and ezio-melotti and removed request for ezio-melotti and CAM-Gerlach January 23, 2023 22:25
@CAM-Gerlach CAM-Gerlach added needs backport to 3.10 only security fixes needs backport to 3.11 only security fixes labels Jan 24, 2023
Copy link
Member

@CAM-Gerlach CAM-Gerlach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks @furkanonder !

@miss-islington
Copy link
Contributor

Thanks @furkanonder for the PR, and @kumaraditya303 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

@bedevere-bot
Copy link

GH-101554 is a backport of this pull request to the 3.11 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.11 only security fixes label Feb 4, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 4, 2023
…dler, traceback, and pdb. (pythonGH-101157)

(cherry picked from commit cef9de6)

Co-authored-by: Furkan Onder <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
@bedevere-bot
Copy link

GH-101555 is a backport of this pull request to the 3.10 branch.

@bedevere-bot bedevere-bot removed the needs backport to 3.10 only security fixes label Feb 4, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Feb 4, 2023
…dler, traceback, and pdb. (pythonGH-101157)

(cherry picked from commit cef9de6)

Co-authored-by: Furkan Onder <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this pull request Feb 4, 2023
…traceback, and pdb. (GH-101157)

(cherry picked from commit cef9de6)

Co-authored-by: Furkan Onder <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
miss-islington added a commit that referenced this pull request Feb 4, 2023
…traceback, and pdb. (GH-101157)

(cherry picked from commit cef9de6)

Co-authored-by: Furkan Onder <[email protected]>
Co-authored-by: C.A.M. Gerlach <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

6 participants