python / python/cpython

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

Đang mở
#123,452 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

docs type-feature
Ngôn ngữ chính
Python
Star
77.2k
Fork
35.9k
Chỉ số merge pull request
Chỉ số pull request đang chờ

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu bằng việc xem xét điều hướng thanh bên của tài liệu, mục lục toàn cục và các URL của phần như /{version}/tutorial/interpreter.html và /{version}/tutorial/. Công việc được xem là hoàn tất khi các màn hình hẹp xác định được phần hiện tại, cung cấp điều hướng quay lại nội dung của phần đó, các ToC của phần liên kết đến ToC toàn cục và giới hạn maxdepth của ToC toàn cục ở mức 2. Một pull request được liên kết đã được tham chiếu trong issue.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
python
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
25/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.