[CI]: Consider/Discuss Tools for Verifying Fenced Code in Markdown Documents
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Feature
- Clarity
- Needs clarification
- Activity status
- Stale
- Tech stack
- markdown, python
- Domain
- ci-cd, documentation, testing
Research direction
Start by reviewing introduction.md, about.md, and instruction.md, then compare doctest, mkcodes, and pmdoctest against their fenced Python examples. Define which strategy handles the documented fences and how CI integration would verify them; done means an agreed tool and evaluation path.
Written by the indexing model from the issue text.
Description
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.
- Dominant language
- Python
- Stars
- 2.5k
- Forks
- 1.5k
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 2
Getting set up
- Ships a Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from exercism/python
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
-
Difficulty 1/5 Under an hour Newbie friendliness 35/100
-
Difficulty 4/5 3-5 days Newbie friendliness 25/100
-
[General Docs] Audit/Cleanup of Track General/Shared DocsPossibly taken @Yrahcaz7 claimed this 6 days ago. Open
-
[Decimals]: New Concept and Concept ExerciseMay be free again @BethanyG claimed this 516 days ago, and no pull request is open. Open
Similar issues
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
snap-stanford/Biomni#380 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
microsoft/playwright-python#3361 ·
Maintainers usually reply within 1 day
-
documentation priority: low size: S status: needs triage
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
cubrid-lab/sqlalchemy-cubrid#1397 ·
Maintainers usually reply within 1 day
-
documentation priority: low size: S status: needs triage
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
cubrid-lab/pycubrid#1307 ·
Maintainers usually reply within 1 day
-
[Bug]: Installer hides SSL certificate errors as bare URLError, and the suggested fix can't workOpenbug
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
ShaftHQ/chaosengine-harness#143 ·
Maintainers usually reply within 1 day