Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open Beginner friendly
  • Is something wrong?
#1,240 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
markdown, python
Domain
documentation, testing-qa

Research direction

Read the conventions section in docs/README.md and the grammar in tests/test_doc_examples.py. Create a temporary Markdown fixture and run python3 tests/test_doc_examples.py <fixture.md> to verify an executed example, a fragment, and a reasoned nocheck exemption. Update only the guide so it matches the checker, while invalid tags and missing output remain errors.

Written by the indexing model from the issue text.

Description

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.
Dominant language
C
Stars
3
Forks
7
Avg merge
3h 56m
Merged PRs (30d)
102

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from InauguralSystems/EigenScript

All issues in InauguralSystems/EigenScript

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.