python / python/cpython

Improve section "Data Structures" in the tutorial

Open
#146,487 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

3.13 3.14 3.15 docs
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Documentation

The "More on Lists" subsection in the "Data Structures" section (Doc/tutorial/datastructures.rst) is the only place in the tutorial that contains formal definitions using Sphinx directives. They mostly duplicate descriptions in the library reference, and index entries refer to ones in the library reference, not in the tutorial. The list class is the only class whose methods are described so in the tutorial. The tutorial perhaps do not need such formal descriptions of all these methods. We could do like with other builtin functions and methods of other builtin classes, and simply add references to their real descriptions.

References to many methods of built classes did not work until recently. This might be one of reasons of exisiting such section.

This was discussed in https://discuss.python.org/t/a-small-typo-on-5-1-more-on-lists-section/106150. cc @nedbat

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with Doc/tutorial/datastructures.rst and its "More on Lists" subsection, then compare the formal method descriptions with their library-reference counterparts. Check the recent discussion for context; done means the tutorial avoids unnecessary duplicated definitions while retaining working references to the real descriptions.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.