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

Đang mở
#1,000 7 bình luận 2 reaction 1 người được giao Xem trên GitHub

@CAM-Gerlach đang làm issue này rồi.

Từ ngày 31/7/2022.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

type-bug type-feature

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

Ngôn ngữ chính
Python
Star
2.1k
Fork
1k
Merge trung bình
2 ngày 12 giờ
Pull request đã merge (30 ngày)
12

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.

Issue khác của python/devguide

Tất cả issue của python/devguide

Issue tương tự

Thêm issue về Python

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.