python / python/cpython

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

未關閉
#123,452 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

docs type-feature
主要語言
Python
星號
77.2k
分支
36k
PR 合併指標
PR 指標待擷取

描述

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

貢獻指南

開啟貢獻指南

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

研究方向

首先檢查文件側邊欄導覽、全域目錄,以及 /{version}/tutorial/interpreter.html 和 /{version}/tutorial/ 等章節 URL。完成的標準是:窄螢幕能夠識別目前的章節,提供返回該章節內容的導覽,將章節 ToCs 連結至全域 ToC,並將全域 ToC 的 maxdepth 限制為 2。issue 中已經參照了一個已連結的 pull request。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
python
領域
documentation
Issue 類型
文件
難度
3/5
預估耗時
1-2 天
活躍度
停滯
描述清晰度
基本清楚
新手友好度
25/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。