Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

docs: update the example-fence guide to the current checker grammar

Aperta Adatta ai principianti
  • Qualcosa non va?
#1,240 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
88/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
markdown, python
Ambito
documentation, testing-qa

Direzione di ricerca

Leggi la sezione sulle convenzioni in docs/README.md e la grammatica in tests/test_doc_examples.py. Crea un fixture Markdown temporaneo ed esegui python3 tests/test_doc_examples.py <fixture.md> per verificare un esempio eseguito, un frammento e un’esenzione nocheck motivata. Aggiorna solo la guida in modo che corrisponda al checker, mentre i tag non validi e l’output mancante continuano a essere errori.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

area:docs documentation good first issue help wanted kind:docs-drift

The documentation guide teaches two example forms that the current example checker rejects. A first-time documentation contributor following the guide will fail the check.

Evidence

docs/README.md, Conventions in these docs says:

  • eigenscript skip marks a deliberately unexecuted example.
  • Code without an output block is an illustrative fragment.

The checker grammar now requires an output pair for an untagged whole program, fragment with declared free names for a snippet, or nocheck <reason> for an explicit exemption. The old skip spelling was removed.

Executed at b91768e23c5a874a64e76e4af9ab291e6aa49983, using temporary Markdown fixtures and python3 tests/test_doc_examples.py <fixture.md>:

Fixture Result
The documented eigenscript skip form Exit 1: unknown fence tag
An untagged example with no output block Exit 1: output block required
Supported output pair, fragment, and reasoned exemption Exit 0: 2 checked, 2 passed, 1 skipped

PR #1175 introduced the current checker behavior but missed this guide; the active documentation PR #1226 does not change docs/README.md.

First-contribution scope

Update only the conventions section to teach the existing supported forms. Explain that untagged runnable examples need output, fragments declare their free variables, and nocheck requires a reason on the fence's opening line. Link to the checker for the full grammar. This needs Markdown familiarity, not runtime expertise.

Done when

  • The guide no longer recommends skip or silently exempting outputless examples.
  • Verify all three supported forms in one small temporary Markdown fixture containing at least one executed example. The checker must accept the forms; a fixture containing only nocheck is rejected for executing zero checks.
  • Invalid/unknown tags and missing output remain errors; do not weaken or edit the checker to match the old guide.
  • The PR records the focused checker command and its results.
Lingua principale
C
Stelle
3
Fork
7
Merge medio
4h 15m
PR unite (30g)
106

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di InauguralSystems/EigenScript

Tutte le issue di InauguralSystems/EigenScript

Issue simili

Altre issue su C

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.