Skip to content

docs: Simplify "More on Lists" section in tutorial#146508

Open
dagangtj wants to merge 1 commit intopython:mainfrom
dagangtj:simplify-more-on-lists
Open

docs: Simplify "More on Lists" section in tutorial#146508
dagangtj wants to merge 1 commit intopython:mainfrom
dagangtj:simplify-more-on-lists

Conversation

@dagangtj
Copy link

@dagangtj dagangtj commented Mar 27, 2026

This PR simplifies the "More on Lists" section in the tutorial by replacing detailed .. method:: directives with concise descriptions and links to the Library Reference.

Changes

  • Replaced 11 detailed .. method:: directive blocks with a simple bullet list
  • Each list item contains a method reference (:meth:~list.method``) and a brief description
  • Added a note directing readers to the Library Reference for complete documentation

Rationale

As noted in #146487:

  • The "More on Lists" subsection was the only place in the tutorial using Sphinx .. method:: directives to provide formal definitions
  • These definitions were largely duplicated from the Library Reference
  • The list class was the only built-in class described in such detail in the tutorial
  • Index entries point to the Library Reference rather than the tutorial

This change brings the list method descriptions in line with how other built-in types (like dict and set) are described in the tutorial—using concise descriptions with links to the full Library Reference documentation.

Verification

  • Documentation builds successfully with make html
  • No warnings or errors introduced

Fixes: #146487


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

Simplify the "More on Lists" section by replacing detailed
.. method:: directives with concise descriptions and links
to the Library Reference.

This change:
- Removes duplicated method definitions that already exist in the Library Reference
- Uses a consistent format matching other built-in types in the tutorial
- Adds clear links to the Library Reference for complete documentation

Fixes: python#146487
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

Improve section "Data Structures" in the tutorial

1 participant