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

Abierto
#1,000 7 comentarios 2 reacciones 1 asignado Ver en GitHub

@CAM-Gerlach ya está trabajando en esto.

Desde el 31/7/2022.

Evaluación

Este issue todavía no se ha evaluado.

Descripción

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

Lenguaje dominante
Python
Estrellas
2.1k
Forks
1k
Merge medio
2 d 12 h
PR fusionados (30 d)
12

Guía de contribución

Abrir la guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de python/devguide

Todos los issues de python/devguide

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.