Skip to content

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
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@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 CAM-Gerlach and ezio-melotti 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 <furkanonder@protonmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
@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 <furkanonder@protonmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
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 <furkanonder@protonmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
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 <furkanonder@protonmail.com>
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
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