doctests
Nobody has claimed this yet.
- Dominant language
- Nix
- Stars
- 4k
- Forks
- 339
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 7
Description
Similar to Rust's doctests.
All nix fenced code blocks will be individually evaluated. This is particularly useful when they contain assertions.
We can be inspired by rustdoc to make follow-up improvements. Most notably, the attributes. Perhaps no_run could be the first.
I'm told that tesh can help with implementation.
note: look into nix-instantiate --eval --strict
It seems there are two primary kinds of examples:
- nix code
- nix repl session
tesh seems to be more appropriate with the repl kind.
These two are different enough that they can be implemented in sequence.
I'm inclined to start with code example doctests.
Contributor 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.
Research direction
Start by reviewing the documentation build and example-processing entry points, then compare Rust doctests with tesh and the noted nix-instantiate --eval --strict approach. The initial scope is fenced Nix code examples: each block should be evaluated individually, with assertions determining success; REPL sessions and attributes such as no_run can follow later.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100