https://github.com/skippi/docspec
A crystal library for automatically testing documentation examples.
https://github.com/skippi/docspec
crystal crystal-lang crystal-language crystal-shard doctest documentation testing
Last synced: 9 days ago
JSON representation
A crystal library for automatically testing documentation examples.
- Host: GitHub
- URL: https://github.com/skippi/docspec
- Owner: skippi
- License: mit
- Created: 2018-05-28T20:26:07.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-06-02T04:41:14.000Z (over 7 years ago)
- Last Synced: 2025-04-01T04:41:23.616Z (7 months ago)
- Topics: crystal, crystal-lang, crystal-language, crystal-shard, doctest, documentation, testing
- Language: Crystal
- Homepage:
- Size: 41 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# docspec
[](https://travis-ci.com/skippi/docspec)
[](https://skippi.github.io/docspec/)
A crystal library for automatically testing documentation examples.
Docspec is crystal's equivalent of a doctest library.
## Use Cases
* Docspec encourages documentation by creating tests from it.
* Docspec encourages testing by reducing boilerplate code for test cases.
* Docspec encourages fast development by reducing boilerplate code for test
cases.
## Installation
Add this to your application's `shard.yml`:
```yaml
dependencies:
docspec:
github: skippi/docspec
```
## Usage
Docspec parses source files for any commented codeblocks with code in them. For
each codeblock line with a prefix of `>>`, it executes the line and stores the
result. If the line also had an expression appended with `# =>`, then docspec
will test that the result equals the appended expression.
Alternatively, you can use the `[](@doctest)` annotation instead of `>>` to
mark entire codeblocks for doctesting.
In this example, we will fully doctest `Foo.bar` and `Foo.baz`, while ignoring doctesting for
`Foo.add`. Note the usage of `>>` and `[](@doctest)`:
```crystal
# src/foo.cr
module Foo
# Returns "hello world".
#
# ```
# >> Foo.bar # => "hello world"
#
# >> name = "say #{Foo.bar}"
# >> name # => "say hello world"
# ```
def self.bar
"hello world"
end
# Subtracts two numbers.
#
# [](@doctest)
# ```
# Foo.baz(4, 2) # => 2
# Foo.baz(-8, -4) # => -4
# ```
def self.baz(a, b)
a - b
end
# Adds two numbers.
#
# ```
# Foo.add(1, 3) # => 4
# Foo.add(-2, -4) # => -6
# ```
def self.add(a, b)
a + b
end
end
```
Require docspec and doctest the source file using a relative path:
```crystal
# spec/foo_spec.cr
require "docspec"
Docspec.doctest("../src/foo.cr")
```
Lastly, run your tests in your project's root directory.
```bash
crystal spec
```
## Documentation
* [Official docs](https://skippi.github.io/docspec/)
## Contributing
1. Fork it ( [https://github.com/skippi/docspec/fork](https://github.com/skippi/docspec/fork) )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request
## Contributors
* [skippi](https://github.com/skippi) - creator, maintainer