python / python/devguide

reST Primer duplicates the Sphinx version; should link to it instead

オープン
#1,000 コメント 7 件 リアクション 2 件 担当者 1 名 GitHub で見る

@CAM-Gerlach がすでに取り組んでいます。

2022年7月31日 から。

type-bug type-feature
主要言語
Python
スター
2.1k
フォーク
1k
平均マージ
2日 12時間
マージ済み PR(30日)
12

説明

Similar to PEP 12, the reST primer in the devguide duplicates the same information in the Sphinx reST primer, along with some bits specific to its particular context.

In fact, unlike PEP 12, they are mostly word for word identical and thus clearly derive from a common source, with the Sphinx version being close to a strict superset of the CPython version, containing some additional and updated sections but also still mentioning many CPython-specific conventions (e.g. section heading format).

This near-duplication is clearly not very DRY, and has several main problems:

  • Additions, improvements and updates/changes to one are not reflected in the other. Clearly, the more appropriate place for this is the Sphinx docs as it is generally applicable to all Sphinx users, and indeed they seem to have been kept much more up to date there, and it also links the full reST reference for each section for readers looking for more information.
  • Readers already familiar with reST or just looking for the CPython-specific bits must either dig through each section, or may skip it entirely and miss them

Therefore, I propose for the Devguide reST primer:

  • Recommending and linking the Sphinx reST primer at the top of the Devguide reST primer section
  • Linking each top-level devguide reST primer section to the corresponding Sphinx section via Intersphinx
  • Eliminating all but the CPython-specific guidance/convention/recommendations in each section

There are also some non-specific bits that could be trimmed from the Additional Markup Constructs section, and each role/directive should be linked to its canonical full Sphinx documentation if present, but that can be addressed separately on a case by case basis.

If we agree this is desirable, I'm willing to take this on, unless @ezio-melotti would prefer to do it.

Somewhat related: python/devguide#916

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

評価

この issue はまだ評価されていません。

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。