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

Ouverte
#2,848 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
25/100
Type d'issue
Fonctionnalité
Clarté
À clarifier
Activité
À l'abandon
Stack technique
markdown, python
Domaine
ci-cd, documentation, testing

Piste de recherche

Commencez par examiner introduction.md, about.md et instruction.md, puis comparez doctest, mkcodes et pmdoctest avec leurs fenced Python examples. Définissez quelle stratégie gère les fences documentés et comment l’intégration CI les vérifierait ; la tâche est considérée comme terminée lorsqu’un outil et un parcours d’évaluation ont été convenus.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.

Langage dominant
Python
Étoiles
2.5k
Forks
1.5k
Aucune PR mergée en 30 j

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de exercism/python

Toutes les issues de exercism/python

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.