Skip to content

Docs: Fix Sphinx warnings in io.rst#107903

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
Merged
erlend-aasland merged 12 commits into from
Aug 17, 2023
Merged

Docs: Fix Sphinx warnings in io.rst #107903

erlend-aasland merged 12 commits into from
Aug 17, 2023

Conversation

@erlend-aasland
Copy link
Contributor

@erlend-aaslanderlend-aasland commented Aug 12, 2023•
edited
Loading

  • Wrap param and arg names with *...*
  • If possible, link to parent class docs for methods like seek, tell, write, read, etc. Else, remove the (already dead) link.
  • Remove links to undocumented constants.

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

@erlend-aaslanderlend-aasland mentioned this pull request Aug 12, 2023
Closed
AA-Turner
AA-Turner reviewed Aug 13, 2023
View reviewed changes
Copy link
Member

@AA-TurnerAA-Turner left a comment

Choose a reason for hiding this comment

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

Some minor comments:

A

Doc/library/io.rst Outdated

In this example, an :class:`EncodingWarning` is emitted for the caller of
``read_text()``.
:meth:`!read_text`.
Copy link
Member

@AA-TurnerAA-TurnerAug 13, 2023

Choose a reason for hiding this comment

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

I think this should stay as read_text(); it refers to the exemplar function defined immediatley above and not to any object description.

Suggested change
:meth:`!read_text`.
``read_text()``

Copy link
ContributorAuthor

@erlend-aaslanderlend-aaslandAug 13, 2023

Choose a reason for hiding this comment

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

I agree. I had an earlier variant where I converted these to the meth markup, but I changed my mind. Probably forgot to revert this one. Thanks for noticing.

Copy link
Member

@AA-TurnerAA-TurnerAug 17, 2023•
edited
Loading

Choose a reason for hiding this comment

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

Did you change your mind on this one? xref 348c115

@erlend-aasland@AA-Turner
Revert unneeded change
6e49ca8
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
@erlend-aaslanderlend-aasland marked this pull request as draft August 14, 2023 10:59
@erlend-aasland
Copy link
ContributorAuthor

erlend-aasland commented Aug 14, 2023

Let's land some of the other changes first; for example documenting SEEK_HOLE and SEEK_DATA.

@erlend-aaslanderlend-aasland marked this pull request as ready for review August 17, 2023 14:23
AA-Turner
AA-Turner approved these changes Aug 17, 2023
View reviewed changes
Copy link
Member

@AA-TurnerAA-Turner left a comment

Choose a reason for hiding this comment

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

Only comment is on read_text (replied to the earlier thread), otherwise looks good!

@erlend-aasland
Copy link
ContributorAuthor

erlend-aasland commented Aug 17, 2023

Thanks for the review!

@erlend-aaslanderlend-aasland enabled auto-merge (squash) August 17, 2023 19:11
@erlend-aaslanderlend-aasland merged commit 5c76899 into python:mainAug 17, 2023
@miss-islington
Copy link
Contributor

miss-islington commented Aug 17, 2023

Thanks @erlend-aasland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

@bedevere-bot
Copy link

bedevere-bot commented Aug 17, 2023

GH-108093 is a backport of this pull request to the 3.12 branch.

@bedevere-botbedevere-bot removed the needs backport to 3.12 only security fixes label Aug 17, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 17, 2023
@erlend-aasland@AA-Turner@miss-islington
Docs: Fix Sphinx warnings in io.rst (pythonGH-107903)
4aba329
- Mark up parameter and argument names properly - If possible, link to docs for methods like `seek`, `tell`, `write`, `read`, etc. (cherry picked from commit 5c76899) Co-authored-by: Erlend E. Aasland <erlend@python.org> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
@bedevere-bot
Copy link

bedevere-bot commented Aug 17, 2023

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

@bedevere-botbedevere-bot removed the needs backport to 3.11 only security fixes label Aug 17, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 17, 2023
@erlend-aasland@AA-Turner@miss-islington
Docs: Fix Sphinx warnings in io.rst (pythonGH-107903)
9a6c998
- Mark up parameter and argument names properly - If possible, link to docs for methods like `seek`, `tell`, `write`, `read`, etc. (cherry picked from commit 5c76899) Co-authored-by: Erlend E. Aasland <erlend@python.org> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
@erlend-aaslanderlend-aasland deleted the docs/fixup-io branch August 17, 2023 19:21
erlend-aasland added a commit that referenced this pull request Aug 17, 2023
@miss-islington@erlend-aasland@AA-Turner
[3.11] Docs: Fix Sphinx warnings in io.rst (GH-107903) (#108094)
b389939
- Mark up parameter and argument names properly - If possible, link to docs for methods like `seek`, `tell`, `write`, `read`, etc. (cherry picked from commit 5c76899) Co-authored-by: Erlend E. Aasland <erlend@python.org> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Yhg1s added a commit that referenced this pull request Aug 18, 2023
@miss-islington@erlend-aasland
@AA-Turner@Yhg1s
[3.12] Docs: Fix Sphinx warnings in io.rst (GH-107903) (#108093)
60edc70
Docs: Fix Sphinx warnings in io.rst (GH-107903) - Mark up parameter and argument names properly - If possible, link to docs for methods like `seek`, `tell`, `write`, `read`, etc. (cherry picked from commit 5c76899) Co-authored-by: Erlend E. Aasland <erlend@python.org> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: T. Wouters <thomas@python.org>
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AA-TurnerAA-TurnerAA-Turner approved these changes

Assignees

No one assigned

Labels

skip issueskip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@erlend-aasland@miss-islington@bedevere-bot@AA-Turner