Skip to content

gh-99030: Added documentation links for types and exceptions #123857

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

Merged
merged 8 commits into from
Oct 21, 2024
Merged

gh-99030: Added documentation links for types and exceptions #123857

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
21b2e9f
Added documentation links for types and exceptions
rruuaanng Sep 9, 2024
d5a0c48
Shortened description sentences
rruuaanng Sep 10, 2024
060bac8
Merge branch 'main' into dev3
rruuaanng Sep 10, 2024
c5edd3e
Change content
rruuaanng Sep 11, 2024
bb60ba1
Merge branch 'main' into dev3
rruuaanng Sep 11, 2024
65dcb43
Change documentation
rruuaanng Oct 16, 2024
0fe175b
Move seealso
rruuaanng Oct 20, 2024
7b66c4c
Add a spaces
rruuaanng Oct 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Doc/library/builtins.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@

This module provides direct access to all 'built-in' identifiers of Python; for
example, ``builtins.open`` is the full name for the built-in function
:func:`open`. See :ref:`built-in-funcs` and :ref:`built-in-consts` for
documentation.
:func:`open`. For more information, see :ref:`built-in-funcs`, :ref:`built-in-consts`,
:ref:`bltin-types` and :ref:`bltin-exceptions`.
Copy link
Contributor

@erlend-aasland erlend-aasland Oct 15, 2024

Choose a reason for hiding this comment

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

A rendered lists of multiple links can be hard on the eye. I suggest instead to use two pieces of Sphinx functionality here:

  1. a list
  2. the seealso directive
Suggested change
:func:`open`. For more information, see :ref:`built-in-funcs`, :ref:`built-in-consts`,
:ref:`bltin-types` and :ref:`bltin-exceptions`.
:func:`open`.
.. seealso::
* :ref:`built-in-consts`
* :ref:`bltin-exceptions`
* :ref:`built-in-funcs`
* :ref:`bltin-types`

Consider also to add this directive at the very bottom of builtins.rst. IMO, it is too prominent at the very top.

cc. @python/editorial-board

Copy link
Contributor Author

@rruuaanng rruuaanng Oct 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Actually, I don't think this needs to be changed because it needs to be a combination, not a list of separate introductions.

Edit:

This module provides direct access to all 'built-in' identifiers of Python; for
example, ``builtins.open`` is the full name for the built-in function
:func:`open`. For more information, see :ref:`built-in-funcs`, :ref:`built-in-consts`,
:ref:`bltin-types` and :ref:`bltin-exceptions`.

This module provides direct access to all 'built-in' identifiers of Python; for
example, ``builtins.open`` is the full name for the built-in function

:func:`open`.

.. seealso::

   * :ref:`built-in-consts`
   * :ref:`bltin-exceptions`
   * :ref:`built-in-funcs`
   * :ref:`bltin-types`

Copy link
Contributor

@willingc willingc Oct 15, 2024

Choose a reason for hiding this comment

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

I agree that applying @erlend-aasland's suggestion makes good sense.

Copy link
Contributor

@erlend-aasland erlend-aasland Oct 18, 2024

Choose a reason for hiding this comment

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

Thanks for addressing my remark. I still think we should consider placing this seealso at the very bottom of the page.

Copy link
Contributor Author

@rruuaanng rruuaanng Oct 19, 2024

Choose a reason for hiding this comment

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

Placing it at the very bottom of the document doesn't seem to be perfect, because it needs to be combined with the above text to form an example. For example, open(), and then the information related to it.

Copy link
Contributor

@willingc willingc Oct 19, 2024

Choose a reason for hiding this comment

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

@rruuaanng Thanks for applying the first suggestion. The second suggestion by @erlend-aasland recommends placing at the bottom of the page. Because this is a short doc file, I agree with Erlend that it makes sense to put at the end of the page. Please make the change to do as suggested.

Coaching tips for contributing to CPython

Your enthusiasm to contribute is causing extra work and reviews by the core team and triagers. To be a more effective contributor, I highly recommend:

  1. Slow down and observe. An effective contributor does not rush since many users depend on our code and its quality.
  2. Ask yourself whether a comment, issue, or PR is necessary or if they would cause unneeded code churn with only minor improvement.
  3. Study and follow the devguide, especially
  4. If a core team member suggests a change, they are doing so to improve your effectiveness as a contributor and to maintain the quality of the codebase.

Thanks in advance for slowing down, and I'm looking forward to improved contributions in the future. 😄

Copy link
Contributor Author

@rruuaanng rruuaanng Oct 20, 2024

Choose a reason for hiding this comment

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

Oh, I'm sorry, maybe it's my lack of experience. It seems that my vision is not as good as that of a core developer. I will continue to work hard and make useful contributions. Please forgive me for not being good at writing documents. Therefore, I will continue to work hard. Thank you for your guidance and erlend.
😄

Copy link
Contributor

@willingc willingc Oct 20, 2024

Choose a reason for hiding this comment

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

Thanks @rruuaanng. Over time, you will find that we are developing collaboratively, and the core developer's suggestions are to improve the code quality and maintainability. Learning to be an effective contributor takes time. Keep the end user in mind, and follow the coaching tips above and I am confident that you will have more success.



This module is not normally accessed explicitly by most applications, but can be
Expand Down