python / python/devguide

Consolidate guidance on prompts in interactive code examples

未關閉
#1,135 3 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

help wanted topic-documentation type-bug type-feature
主要語言
Python
星號
2.1k
分支
1k
平均合併
2 天 12 小時
30 天內合併 PR
12

描述

In the Documentation chapter, Style Guide / Code Examples has

The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations.

(Perhaps it should be mentioned here that doctesting the code example requires such differentiation and hence requires secondary prompts. Perhaps the primary prompt should also be left off.)

reStructured Text Markup / Additional Markup Constructs / Showing Code Examples has

Representing an interactive session requires including the prompts and output along with the Python code. No special markup is required for interactive sessions. After the last line of input or output presented, there should not be an “unused” primary prompt; this is an example of what not to do:

>>>1 + 1
2
>>>

I think both advices should be in the same place and a reference added in the other.

貢獻指南

開啟貢獻指南

從這裡開始

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

研究方向

先開啟連結的「Style Guide / Code Examples」和「reStructured Text Markup / Showing Code Examples」章節。將它們對互動式提示的指引整合到一處,在另一處加入參考,並確保最終的建議涵蓋次要提示、doctesting 以及未使用的主要提示範例。

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

評估

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

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

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