Skip to content

Docs: Fix Sphinx warnings in io.rst - #107903

Merged
erlend-aasland merged 12 commits into
python:mainfrom
erlend-aasland:docs/fixup-io
Aug 17, 2023
Merged

Docs: Fix Sphinx warnings in io.rst#107903
erlend-aasland merged 12 commits into
python:mainfrom
erlend-aasland:docs/fixup-io

Conversation

@erlend-aasland

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

Copy link
Copy Markdown
Contributor
  • 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

@AA-TurnerAA-Turner left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Some minor comments:

A

Comment threadDoc/library/io.rst Outdated

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

@AA-TurnerAA-TurnerAug 13, 2023

Copy link
Copy Markdown
Member

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

@erlend-aaslanderlend-aaslandAug 13, 2023

Copy link
Copy Markdown
ContributorAuthor

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.

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

Copy link
Copy Markdown
Member

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

Comment threadDoc/library/io.rst
Comment threadDoc/library/io.rst Outdated
Comment threadDoc/library/io.rst
Comment threadDoc/library/io.rst
@erlend-aasland@AA-Turner
Revert unneeded change
6e49ca8
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
@erlend-aasland
erlend-aasland marked this pull request as draft August 14, 2023 10:59
@erlend-aasland

erlend-aasland commented Aug 14, 2023

Copy link
Copy Markdown
ContributorAuthor

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

@erlend-aasland
erlend-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

@AA-TurnerAA-Turner left a comment

Copy link
Copy Markdown
Member

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

erlend-aasland commented Aug 17, 2023

Copy link
Copy Markdown
ContributorAuthor

Thanks for the review!

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

miss-islington commented Aug 17, 2023

Copy link
Copy Markdown
Contributor

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

@bedevere-bot

bedevere-bot commented Aug 17, 2023

Copy link
Copy Markdown

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

bedevere-bot commented Aug 17, 2023

Copy link
Copy Markdown

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-aasland
erlend-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