Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

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

Đang mở Phù hợp với người mới
  • Có gì không ổn?
#1,240 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
88/100
Loại issue
Tài liệu
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
markdown, python
Lĩnh vực
documentation, testing-qa

Hướng nghiên cứu

Đọc phần quy ước trong docs/README.md và ngữ pháp trong tests/test_doc_examples.py. Tạo một fixture Markdown tạm thời và chạy python3 tests/test_doc_examples.py <fixture.md> để xác minh một ví dụ được thực thi, một fragment và một ngoại lệ nocheck có lý do. Chỉ cập nhật hướng dẫn để khớp với checker, còn các tag không hợp lệ và đầu ra bị thiếu vẫn phải là lỗi.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
C
Star
3
Fork
7
Merge trung bình
3 giờ 56 phút
Pull request đã merge (30 ngày)
102

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của InauguralSystems/EigenScript

Tất cả issue của InauguralSystems/EigenScript

Issue tương tự

Thêm issue về C

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.