[CI]: Consider/Discuss Tools for Verifying Fenced Code in Markdown Documents

Abierto
#2,848 1 comentario 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Necesita aclaración
Estado de actividad
Estancado
Stack tecnológico
markdown, python

Línea de trabajo

Empieza revisando introduction.md, about.md e instruction.md; después compara doctest, mkcodes y pmdoctest con sus fenced Python examples. Define qué estrategia gestiona los fences documentados y cómo la integración de CI los verificaría; se considera terminado cuando haya un acuerdo sobre una herramienta y un proceso de evaluación.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

discussion 💬

This came up in discussing PR #2838, so opening an issue here for longer discussion/evaluation.

We currently "hand validate" example python code used in introduction.md, about.md, and instruction.md and similar documents. This leads to errors where certain code will not work in the REPL, or syntax or other errors get made and published. As we scale up exercises, this doesn't feel like a sustainable solution, hence this issue to propose, evaluate, and track possible tools and strategies for verifying code , and (possibly) adding that verification to the track CI.

Below are three applicable libraries, but I'd warmly welcome more. Of the three below, pmdoctest feels like the nicest solution, and I've run the comparisons concept exercise through it with reasonable results. But I'd like to see if there are other strategies/libraries out there.

doctest - this is the old-school original, but doesn't really work well in markdown fences.
mkcodes - have not tried this yet.
pmdoctest - reasonably good, but requires some weird quirks with code fence language names and or excess >>> in code fences to make parsing work.

Lenguaje dominante
Python
Estrellas
2.5k
Forks
1.5k
Merge medio
2 d 17 h
PR fusionados (30 d)
2

Preparar el entorno

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 exercism/python

Todos los issues de exercism/python

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.