exercism / exercism/python

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

未關閉
#2,848 1 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
discussion 💬
主要語言
Python
星號
2.5k
分支
1.5k
PR 合併指標
30 天內沒有已合併 PR

描述

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](https://docs.python.org/3/library/doctest.html) - this is the old-school original, but doesn't really work well in markdown fences.
[mkcodes](https://github.com/ryneeverett/mkcodes) - have not tried this yet.
[pmdoctest](https://tmarktaylor.github.io/phmdoctest/) - reasonably good, but requires some weird quirks with code fence language names and or excess `>>>` in code fences to make parsing work.

貢獻指南

開啟貢獻指南

研究方向

先檢閱 introduction.md、about.md 和 instruction.md,接著將 doctest、mkcodes 和 pmdoctest 分別與其 fenced Python examples 進行比較。定義哪種策略能處理文件中的 fences,以及 CI integration 將如何驗證它們;達成對工具與評估路徑的共識即表示完成。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
markdown, python
領域
ci-cd, documentation, testing
Issue 類型
功能
難度
5/5
預估耗時
一週以上
活躍度
停滯
描述清晰度
需要釐清
新手友好度
25/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。