python / python/cpython

Within-section navigation missing for smaller screens, global contents difficult to navigate.

Open
#123,452 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs type-feature
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Documentation

Problem

Within a documentation section (I'm using that term to refer to sub-documents like, say, the tutorial, not sure if there is an official term), there is currently no way to go "up" a level to see the contents of that section when not using a full width screen:

Screenshot 2024-08-28 at 7 20 21 PM

Full width screens have breadcrumbs at the top

Screenshot 2024-08-28 at 7 21 07 PM

The "table of contents" link takes you back to the global contents, which are not usable, as they contain every header from every document in the docs - take a scroll if you haven't in awhile: https://docs.python.org/3/contents.html

It's also not obvious which document you are in, as "table of contents" is ambiguous - the only place that "tutorial" is present is in the URL.

This makes it quite challenging to navigate the docs on mobile, or when splitting a screen and reading in a narrow window.

Desired solution

I would like...

  • the sidebar "Table of Contents" to be replaced with the title of current document section when one is within a document section (eg. /{version}/tutorial/interpreter.html), and with a link to the global ToC when one is in a section ToC (eg. /{version}/tutorial/).
  • The maxdepth of the global ToC to be reduced to 2 to make it usable

I will follow on with a PR momentarily...

Linked PRs
  • gh-123453

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 by reviewing the documentation sidebar navigation, the global table of contents, and section URLs such as /{version}/tutorial/interpreter.html and /{version}/tutorial/. Done means narrow screens identify the current section, provide navigation back to its section contents, link section ToCs to the global ToC, and limit the global ToC maxdepth to 2. A linked pull request is already referenced in the issue.

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
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.