Skip to content

Docs: Fix Sphinx warnings in sys.rst #108106

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
merged 11 commits into from
Aug 20, 2023
Merged

Docs: Fix Sphinx warnings in sys.rst #108106

merged 11 commits into from
Aug 20, 2023

Conversation

erlend-aasland
Copy link
Contributor

@erlend-aasland erlend-aasland commented Aug 18, 2023 •
edited
Loading

  • Mark up named tuple attributes using .. attribute:: member
  • Remove links for external functions
  • Use list-table markup where appropriate
  • io.BufferedIOBase has no 'buffer' attribute; remove the link and mark up using :attr:`!buffer`

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

@erlend-aasland
Docs: Fix Sphinx warnings in sys.rst
53eca7b 
- Mark up named tuple attributes using :attr:`!member`
- Remove links for external functions
- io.BufferedIOBase has no 'buffer' attribute;
  remove the link and mark up using :attr:`!buffer`
@erlend-aasland erlend-aasland marked this pull request as ready for review August 18, 2023 08:45
@erlend-aasland erlend-aasland added docs Documentation in the Doc dir skip issue skip news needs backport to 3.11 only security fixes needs backport to 3.12 only security fixes and removed awaiting core review labels Aug 18, 2023
AlexWaygood
AlexWaygood reviewed Aug 18, 2023
View reviewed changes
AA-Turner
AA-Turner reviewed Aug 18, 2023
View reviewed changes
@erlend-aasland
Copy link
Contributor Author

GitHub does not cooperate today; I'll apply the suggested changes locally and push instead.

@erlend-aasland
Copy link
Contributor Author

@AA-Turner, I don't understand the Sphinx warning/failure; can it be a bug in Sphinx?

Doc/library/textwrap.rst
60: more than one target found for cross-reference 'width': sys.hash_info.width, textwrap.TextWrapper.width
Error: Process completed with exit code 255.

@erlend-aasland
Copy link
Contributor Author

@AA-Turner, I don't understand the Sphinx warning/failure; can it be a bug in Sphinx?

Doc/library/textwrap.rst
60: more than one target found for cross-reference 'width': sys.hash_info.width, textwrap.TextWrapper.width
Error: Process completed with exit code 255.

It seems to me the textwrap docs are incorrectly marked up. It textwrap.rst, it looks like width and placeholder are meant to refer to the arguments, not attributes:

diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst
index a150eefbf9..e2952ce3cc 100644
--- a/Doc/library/textwrap.rst
+++ b/Doc/library/textwrap.rst
@@ -60,7 +60,7 @@ functions should be good enough; otherwise, you should use an instance of
    First the whitespace in *text* is collapsed (all whitespace is replaced by
    single spaces).  If the result fits in the *width*, it is returned.
    Otherwise, enough words are dropped from the end so that the remaining words
-   plus the :attr:`.placeholder` fit within :attr:`.width`::
+   plus the *placeholder* fit within *width*::
 
       >>> textwrap.shorten("Hello  world!", width=12)
       'Hello world!'

AA-Turner
AA-Turner approved these changes Aug 19, 2023
View reviewed changes
erlend-aasland
erlend-aasland commented Aug 19, 2023
View reviewed changes
AlexWaygood
AlexWaygood reviewed Aug 19, 2023
View reviewed changes
AlexWaygood
AlexWaygood reviewed Aug 19, 2023
View reviewed changes
AlexWaygood
AlexWaygood approved these changes Aug 20, 2023
View reviewed changes
Copy link
Member

@AlexWaygood AlexWaygood 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!

AA-Turner
AA-Turner approved these changes Aug 20, 2023
View reviewed changes
Copy link
Member

@AA-Turner AA-Turner left a comment

Choose a reason for hiding this comment

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

Looks good!

A

@erlend-aasland
Copy link
Contributor Author

Thanks for the reviews and suggestions, Adam and Alex!

@erlend-aasland erlend-aasland merged commit 29fa7af into python:main Aug 20, 2023
@miss-islington
Copy link
Contributor

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

@miss-islington
Copy link
Contributor

Sorry, @erlend-aasland, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 29fa7afef94d74e18d97485c085d1ccf80c16ca3 3.12

@erlend-aasland erlend-aasland deleted the docs/cleanup-sys branch August 20, 2023 11:09
@bedevere-bot
Copy link

GH-108166 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 Aug 20, 2023
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 20, 2023
@erlend-aasland @AlexWaygood
@AA-Turner @miss-islington
Docs: Fix Sphinx warnings in sys.rst (pythonGH-108106)
2ec2df1 
- Mark up named tuple attributes as attributes
- Remove links for external functions
- io.BufferedIOBase has no 'buffer' attribute;
  remove the link and mark up using :attr:`!buffer`
- (Re)format some tables as bullet lists:
  - sys._emscripten_info
  - sys.hash_info
  - sys.int_info
  - sys.thread_info
- In the paragraphs mentioning 'f_trace_lines' and 'f_trace_opcodes',
  add links to the frame objects reference.

(cherry picked from commit 29fa7af)

Co-authored-by: Erlend E. Aasland <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
kumaraditya303 pushed a commit that referenced this pull request Aug 20, 2023
@miss-islington @erlend-aasland
@AlexWaygood @AA-Turner
[3.11] Docs: Fix Sphinx warnings in sys.rst (GH-108106) (#108166)
5af34d2 
Docs: Fix Sphinx warnings in sys.rst (GH-108106)

- Mark up named tuple attributes as attributes
- Remove links for external functions
- io.BufferedIOBase has no 'buffer' attribute;
  remove the link and mark up using :attr:`!buffer`
- (Re)format some tables as bullet lists:
  - sys._emscripten_info
  - sys.hash_info
  - sys.int_info
  - sys.thread_info
- In the paragraphs mentioning 'f_trace_lines' and 'f_trace_opcodes',
  add links to the frame objects reference.

(cherry picked from commit 29fa7af)

Co-authored-by: Erlend E. Aasland <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
@bedevere-bot
Copy link

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

@bedevere-bot bedevere-bot removed the needs backport to 3.12 only security fixes label Aug 20, 2023
erlend-aasland added a commit to erlend-aasland/cpython that referenced this pull request Aug 20, 2023
@erlend-aasland @AlexWaygood @AA-Turner
[3.12] Docs: Fix Sphinx warnings in sys.rst (python#108106)
7ec9d2a 
(cherry picked from commit 29fa7af)

- Mark up named tuple attributes as attributes
- Remove links for external functions
- io.BufferedIOBase has no 'buffer' attribute;
  remove the link and mark up using :attr:`!buffer`
- (Re)format some tables as bullet lists:
  - sys._emscripten_info
  - sys.hash_info
  - sys.int_info
  - sys.thread_info
- In the paragraphs mentioning 'f_trace_lines' and 'f_trace_opcodes',
  add links to the frame objects reference.

Co-authored-by: Alex Waygood <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
Yhg1s pushed a commit that referenced this pull request Aug 20, 2023
@erlend-aasland @AlexWaygood @AA-Turner
[3.12] Docs: Fix Sphinx warnings in sys.rst (#108106) (#108178)
399825e 
(cherry picked from commit 29fa7af)

- Mark up named tuple attributes as attributes
- Remove links for external functions
- io.BufferedIOBase has no 'buffer' attribute;
  remove the link and mark up using :attr:`!buffer`
- (Re)format some tables as bullet lists:
  - sys._emscripten_info
  - sys.hash_info
  - sys.int_info
  - sys.thread_info
- In the paragraphs mentioning 'f_trace_lines' and 'f_trace_opcodes',
  add links to the frame objects reference.

Co-authored-by: Alex Waygood <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@AA-Turner AA-Turner AA-Turner approved these changes

@AlexWaygood AlexWaygood AlexWaygood approved these changes

Assignees

@erlend-aasland erlend-aasland

Labels
docs Documentation in the Doc dir skip issue skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@erlend-aasland @miss-islington @bedevere-bot @AA-Turner @AlexWaygood