diff --git a/.gitignore b/.gitignore index 6f47d624..c887f96c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ /dist-newstyle/ /.stack-work/ /ghci-wrapper/.stack-work/ +/doc/gh-md-toc diff --git a/README.md b/README.md index 3d20b416..87194cb7 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,41 @@ # Doctest: Test interactive Haskell examples -`doctest` is a small program, that checks [examples in Haddock comments](http://www.haskell.org/haddock/doc/html/ch03s08.html#id566093). It is similar -to the [popular Python module with the same name](http://docs.python.org/library/doctest.html). - +`doctest` is a tool that checks +[examples](https://www.haskell.org/haddock/doc/html/ch03s08.html#idm140354810775744) +and +[properties](https://www.haskell.org/haddock/doc/html/ch03s08.html#idm140354810771856) +in Haddock comments. +It is similar in spirit to the [popular Python module with the same name](https://docs.python.org/3/library/doctest.html). + +* [Getting started](#getting-started) + * [Installation](#installation) + * [A basic example](#a-basic-example) + * [Running doctest for a Cabal package](#running-doctest-for-a-cabal-package) +* [Writing examples and properties](#writing-examples-and-properties) + * [Example groups](#example-groups) + * [A note on performance](#a-note-on-performance) + * [Setup code](#setup-code) + * [Multi-line input](#multi-line-input) + * [Multi-line output](#multi-line-output) + * [Matching arbitrary output](#matching-arbitrary-output) + * [QuickCheck properties](#quickcheck-properties) + * [Hiding examples from Haddock](#hiding-examples-from-haddock) + * [Using GHC extensions](#using-ghc-extensions) +* [Limitations](#limitations) +* [Doctest in the wild](#doctest-in-the-wild) +* [Development](#development) +* [Contributors](#contributors) + + +# Getting started ## Installation `doctest` is available from [Hackage](http://hackage.haskell.org/cgi-bin/hackage-scripts/package/doctest). -Install it, by typing: +Install it with: - cabal install doctest + cabal update && cabal install doctest Make sure that Cabal's `bindir` is on your `PATH`. @@ -26,15 +51,14 @@ On Windows: set PATH="%AppData%\cabal\bin\;%PATH%" -For more information, see the [section on paths in the Cabal User Guide](http://www.haskell.org/cabal/users-guide/installing-packages.html#paths-in-the-simple-build-system). - -## Usage +## A basic example Below is a small Haskell module. The module contains a Haddock comment with some examples of interaction. The examples demonstrate how the module is supposed to be used. ```haskell +-- src/Fib.hs module Fib where -- | Compute Fibonacci numbers @@ -50,6 +74,7 @@ fib :: Int -> Int fib 0 = 0 fib 1 = 1 fib n = fib (n - 1) + fib (n - 2) + ``` (A comment line starting with `>>>` denotes an _expression_. @@ -58,21 +83,59 @@ Result is defined by what a [REPL](http://en.wikipedia.org/wiki/Read-eval-print_loop) (e.g. ghci) prints to `stdout` and `stderr` when evaluating that expression.) -With `doctest` you may check whether the implementation satisfies the given examples, by typing: +With `doctest` you can check whether the implementation satisfies the given +examples: + +``` +doctest src/Fib.hs +``` + + +## Running `doctest` for a Cabal package + +The easiest way to run `doctest` for a Cabal package is via `cabal repl --with-ghc=doctest`. - doctest Fib.hs +This doesn't make a big difference for a simple package, but in more involved +situations `cabal` will make sure that all dependencies are available and it +will pass any required GHC options to `doctest`. -You may produce Haddock documentation for that module with: +A simple `.cabal` file for `Fib` looks like this: + +```cabal +-- fib.cabal +cabal-version: 1.12 + +name: fib +version: 0.0.0 +build-type: Simple + +library + build-depends: base == 4.* + hs-source-dirs: src + exposed-modules: Fib + default-language: Haskell2010 + +``` + +With a `.cabal` file in place, it is possible to run `doctest` via `cabal repl`: + +``` +cabal install doctest --overwrite-policy=always && cabal build && cabal repl --build-depends=QuickCheck --with-ghc=doctest +``` - haddock -h Fib.hs -o doc/ +Notes: -`doctest` will fail on comments that `haddock` also doesn't like. -Sometimes (e.g., [#251](https://github.com/sol/doctest/issues/251)), this means that `doctest` will fail on input that GHC accepts. +- `doctest` always uses the version of GHC it was compiled with. Reinstalling + `doctest` with `cabal install doctest --overwrite-policy=always` before each + invocation ensures that it uses the same version of GHC as is on the `PATH`. +- Technically, `cabal build` is not necessary. `cabal repl --with-ghc=doctest` + will build any dependencies as needed. However, it's more robust to run + `cabal build` first (specifically it is not a good idea to build + `ghc-paths` with `--with-ghc=doctest`). -`doctest` likes UTF-8. If you are running it with, e.g., `LC_ALL=C`, -you may need to invoke `doctest` with `LC_ALL=C.UTF-8`. +# Writing examples and properties -### Example groups +## Example groups Examples from a single Haddock comment are grouped together and share the same scope. E.g. the following works: @@ -94,9 +157,9 @@ for -- >>> print n ``` -`print n` is not tried, because `let n = x + y` fails (`y` is not in scope!). +`print n` is skipped, because `let n = x + y` fails (as `y` is not in scope). -#### A note on performance +### A note on performance By default, `doctest` calls `:reload` between each group to clear GHCi's scope of any local definitions. This ensures that previous examples cannot influence @@ -112,7 +175,7 @@ the performance of `--fast` suffers significantly when combined with the `--preserve-it` flag (which keeps the value of GHCi's `it` value between examples). -### Setup code +## Setup code You can put setup code in a [named chunk][named-chunks] with the name `$setup`. The setup code is run before each example group. If the setup code produces @@ -142,7 +205,7 @@ code right after import declarations, but due to its declarative nature you can place it anywhere inbetween top level declarations as well. -### Multi-line input +## Multi-line input GHCi supports commands which span multiple lines, and the same syntax works for doctest: ```haskell @@ -186,7 +249,7 @@ works = 3 broken = 3 ``` -### Multi-line output +## Multi-line output If there are no blank lines in the output, multiple lines are handled automatically. @@ -221,7 +284,7 @@ doubleSpace :: String -> String doubleSpace = (intercalate "\n\n") . lines ``` -### Matching arbitrary output +## Matching arbitrary output Any lines containing only three dots (`...`) will match one or more lines with arbitrary content. For instance, @@ -242,10 +305,10 @@ anything *within that line*: -- foo ... baz ``` -### QuickCheck properties +## QuickCheck properties -Haddock (since version 2.13.0) has markup support for properties. Doctest can -verify properties with QuickCheck. A simple property looks like this: +Haddock has markup support for properties. Doctest can verify properties with +QuickCheck. A simple property looks like this: ```haskell -- | @@ -282,8 +345,8 @@ fib n = fib (n - 1) + fib (n - 2) ``` If you see an error like the following, ensure that -[QuickCheck](http://hackage.haskell.org/package/QuickCheck) is a dependency -of the test-suite or executable running `doctest`. +[QuickCheck](http://hackage.haskell.org/package/QuickCheck) is visible to +`doctest` (e.g. by passing `--build-depends=QuickCheck` to `cabal repl`). ```haskell :39:3: @@ -298,7 +361,7 @@ of the test-suite or executable running `doctest`. In the splice: $(polyQuickCheck (mkName "doctest_prop")) ``` -### Hiding examples from Haddock +## Hiding examples from Haddock You can put examples into [named chunks][named-chunks], and not refer to them in the export list. That way they will not be part of the generated Haddock @@ -312,18 +375,19 @@ documentation, but Doctest will still find them. [named-chunks]: http://www.haskell.org/haddock/doc/html/ch03s05.html -### Using GHC extensions +## Using GHC extensions There's two sets of GHC extensions involved when running Doctest: 1. The set of GHC extensions that are active when compiling the module code -(excluding the doctest examples). The easiest way to specify these extensions -is through [LANGUAGE pragmas][language-pragma] in your source files. -(Doctest will not look at your cabal file.) -2. The set of GHC extensions that are active when executing the Doctest -examples. (These are not influenced by the LANGUAGE pragmas in the file.) The -recommended way to enable extensions for Doctest examples is to switch them -on like this: + (excluding the doctest examples). The easiest way to specify these + extensions is through [LANGUAGE pragmas][language-pragma] in your source + files. + +1. The set of GHC extensions that are active when executing the Doctest + examples. (These are not influenced by the LANGUAGE pragmas in the file.) + The recommended way to enable extensions for Doctest examples is to switch + them on like this: ```haskell -- | @@ -350,68 +414,49 @@ Haddock](#hiding-examples-from-haddock), e.g.: -- >>> :set -XTupleSections ``` -[language-pragma]: http://www.haskell.org/ghc/docs/latest/html/users_guide/pragmas.html#language-pragma +[language-pragma]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/exts/pragmas.html#language-pragma -### Limitations +# Limitations -Due to [a GHC bug](https://gitlab.haskell.org/ghc/ghc/-/issues/20670), running -`:set -XTemplateHaskell` within `ghci` may unload any modules that were -specified on the command line. -To address this `doctest >= 0.19.0` does two things: +- Doctests only works on platforms that have support for GHC's `--interactive` mode (`ghci`). -1. Doctest always enables `-XTemplateHaskell`. So it is safe to use Template - Haskell in examples without enabling the extension explicitly. -1. Doctest filters out `-XTemplateHaskell` from single-line `:set`-statements. - So it is still safe to include `:set -XTemplateHaskell` in examples for - documentation purposes. It may just not work as intended in `ghci` due to - that GHC bug. -Doctest does not filter out `-XTemplateHaskell` from multi-line -`:set`-statements. So if you e.g. use +- Due to [a GHC bug](https://gitlab.haskell.org/ghc/ghc/-/issues/20670), running + `:set -XTemplateHaskell` within `ghci` may unload any modules that were + specified on the command-line. -``` ->>> :{ -:set -XTemplateHaskell -:} -``` -then you are on your own. + To address this `doctest >= 0.19.0` does two things: + 1. Doctest always enables `-XTemplateHaskell`. So it is safe to use Template + Haskell in examples without enabling the extension explicitly. + 1. Doctest filters out `-XTemplateHaskell` from single-line `:set`-statements. + So it is still safe to include `:set -XTemplateHaskell` in examples for + documentation purposes. It may just not work as intended in `ghci` due to + that GHC bug. -### Cabal integration + Doctest does not filter out `-XTemplateHaskell` from multi-line + `:set`-statements. So if you e.g. use -Doctest provides both, an executable and a library. The library exposes a -function `doctest` of type: + ``` + >>> :{ + :set -XTemplateHaskell + :} + ``` + then you are on your own. -```haskell -doctest :: [String] -> IO () -``` + Note that all platforms that support `--interactive` also support + `-XTemplateHaskell`. So this approach does not reduce Doctest's platform + support. -Doctest's own `main` is simply: +- Modules that are rejected by `haddock` will not work with `doctest`. This + can mean that `doctest` fails on input that is accepted by GHC (e.g. + [#251](https://github.com/sol/doctest/issues/251)). -```haskell -main = getArgs >>= doctest -``` +- Doctest works best with UTF-8. If your locale is e.g. `LC_ALL=C`, you may + want to invoke `doctest` with `LC_ALL=C.UTF-8`. -Consequently, it is possible to create a custom executable for a project, by -passing all command-line arguments that are required for that project to -`doctest`. A simple example looks like this: - -```haskell --- file doctests.hs -import Test.DocTest -main = doctest ["-isrc", "src/Main.hs"] -``` - -And a corresponding Cabal test suite section like this: - - test-suite doctests - type: exitcode-stdio-1.0 - ghc-options: -threaded - main-is: doctests.hs - build-depends: base, doctest >= 0.8 - -## Doctest in the wild +# Doctest in the wild You can find real world examples of `Doctest` being used below: @@ -419,23 +464,17 @@ You can find real world examples of `Doctest` being used below: * [base Data/Functor.hs](https://github.com/ghc/ghc/blob/669cbef03c220de43b0f88f2b2238bf3c02ed64c/libraries/base/Data/Functor.hs#L34-L64) -## Doctest extensions - - * [doctest-discover](https://github.com/karun012/doctest-discover) - -## Development [![Build Status](https://secure.travis-ci.org/sol/doctest.png)](http://travis-ci.org/sol/doctest) - -Join in at `#hspec` on freenode. +# Development Discuss your ideas first, ideally by opening an issue on GitHub. Add tests for new features, and make sure that the test suite passes with your changes. - cabal configure --enable-tests && cabal build && cabal exec cabal test + cabal build --enable-tests && cabal exec -- cabal test --test-show-details=direct -## Contributors +# Contributors * Adam Vogt * Alan Zimmerman diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..b4febeeb --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,6 @@ +all: gh-md-toc + inject < README.template.md > ../README.md + +gh-md-toc: + wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/0.8.0/gh-md-toc + chmod +x $@ diff --git a/doc/README.template.md b/doc/README.template.md new file mode 100644 index 00000000..223d061b --- /dev/null +++ b/doc/README.template.md @@ -0,0 +1,474 @@ +# Doctest: Test interactive Haskell examples + +`doctest` is a tool that checks +[examples](https://www.haskell.org/haddock/doc/html/ch03s08.html#idm140354810775744) +and +[properties](https://www.haskell.org/haddock/doc/html/ch03s08.html#idm140354810771856) +in Haddock comments. +It is similar in spirit to the [popular Python module with the same name](https://docs.python.org/3/library/doctest.html). + +{{ bash gh-md-toc - < README.template.md | tail -n +2 }} + +# Getting started + +## Installation + +`doctest` is available from +[Hackage](http://hackage.haskell.org/cgi-bin/hackage-scripts/package/doctest). +Install it with: + + cabal update && cabal install doctest + +Make sure that Cabal's `bindir` is on your `PATH`. + +On Linux: + + export PATH="$HOME/.cabal/bin:$PATH" + +On Mac OS X: + + export PATH="$HOME/Library/Haskell/bin:$PATH" + +On Windows: + + set PATH="%AppData%\cabal\bin\;%PATH%" + +## A basic example + +Below is a small Haskell module. +The module contains a Haddock comment with some examples of interaction. +The examples demonstrate how the module is supposed to be used. + +```haskell +-- src/Fib.hs +{{ cat example/src/Fib.hs }} +``` + +(A comment line starting with `>>>` denotes an _expression_. +All comment lines following an expression denote the _result_ of that expression. +Result is defined by what a +[REPL](http://en.wikipedia.org/wiki/Read-eval-print_loop) (e.g. ghci) +prints to `stdout` and `stderr` when evaluating that expression.) + +With `doctest` you can check whether the implementation satisfies the given +examples: + +``` +doctest src/Fib.hs +``` + + +## Running `doctest` for a Cabal package + +The easiest way to run `doctest` for a Cabal package is via `cabal repl --with-ghc=doctest`. + +This doesn't make a big difference for a simple package, but in more involved +situations `cabal` will make sure that all dependencies are available and it +will pass any required GHC options to `doctest`. + +A simple `.cabal` file for `Fib` looks like this: + +```cabal +-- fib.cabal +{{ cat example/fib.cabal }} +``` + +With a `.cabal` file in place, it is possible to run `doctest` via `cabal repl`: + +``` +cabal install doctest --overwrite-policy=always && cabal build && cabal repl --build-depends=QuickCheck --with-ghc=doctest +``` + +Notes: + +- `doctest` always uses the version of GHC it was compiled with. Reinstalling + `doctest` with `cabal install doctest --overwrite-policy=always` before each + invocation ensures that it uses the same version of GHC as is on the `PATH`. +- Technically, `cabal build` is not necessary. `cabal repl --with-ghc=doctest` + will build any dependencies as needed. However, it's more robust to run + `cabal build` first (specifically it is not a good idea to build + `ghc-paths` with `--with-ghc=doctest`). + +# Writing examples and properties + +## Example groups + +Examples from a single Haddock comment are grouped together and share the same +scope. E.g. the following works: + +```haskell +-- | +-- >>> let x = 23 +-- >>> x + 42 +-- 65 +``` + +If an example fails, subsequent examples from the same group are skipped. E.g. +for + +```haskell +-- | +-- >>> let x = 23 +-- >>> let n = x + y +-- >>> print n +``` + +`print n` is skipped, because `let n = x + y` fails (as `y` is not in scope). + +### A note on performance + +By default, `doctest` calls `:reload` between each group to clear GHCi's scope +of any local definitions. This ensures that previous examples cannot influence +later ones. However, it can lead to performance penalties if you are using +`doctest` in a project with many modules. One possible remedy is to pass the +`--fast` flag to `doctest`, which disables calling `:reload` between groups. +If `doctest`s are running too slowly, you might consider using `--fast`. +(With the caveat that the order in which groups appear now matters!) + +However, note that due to a +[bug on GHC 8.2.1 or later](https://ghc.haskell.org/trac/ghc/ticket/14052), +the performance of `--fast` suffers significantly when combined with the +`--preserve-it` flag (which keeps the value of GHCi's `it` value between +examples). + +## Setup code + +You can put setup code in a [named chunk][named-chunks] with the name `$setup`. +The setup code is run before each example group. If the setup code produces +any errors/failures, all tests from that module are skipped. + +Here is an example: + +```haskell +module Foo where + +import Bar.Baz + +-- $setup +-- >>> let x = 23 :: Int + +-- | +-- >>> foo + x +-- 65 +foo :: Int +foo = 42 +``` + +Note that you should not place setup code inbetween the module header (`module +... where`) and import declarations. GHC will not be able to parse it ([issue + #167](https://github.com/sol/doctest/issues/167)). It is best to place setup +code right after import declarations, but due to its declarative nature you can +place it anywhere inbetween top level declarations as well. + + +## Multi-line input +GHCi supports commands which span multiple lines, and the same syntax works for doctest: + +```haskell +-- | +-- >>> :{ +-- let +-- x = 1 +-- y = 2 +-- in x + y + multiline +-- :} +-- 6 +multiline = 3 +``` + +Note that `>>>` can be left off for the lines following the first: this is so that +haddock does not strip leading whitespace. The expected output has whitespace +stripped relative to the :}. + +Some peculiarities on the ghci side mean that whitespace at the very start is lost. +This breaks the example `broken`, since the x and y aren't aligned from ghci's +perspective. A workaround is to avoid leading space, or add a newline such +that the indentation does not matter: + +```haskell +{- | >>> :{ +let x = 1 + y = 2 + in x + y + works +:} +6 +-} +works = 3 + +{- | >>> :{ + let x = 1 + y = 2 + in x + y + broken +:} +3 +-} +broken = 3 +``` + +## Multi-line output +If there are no blank lines in the output, multiple lines are handled +automatically. + +```haskell +-- | >>> putStr "Hello\nWorld!" +-- Hello +-- World! +``` + +If however the output contains blank lines, they must be noted +explicitly with ``. For example, + +```haskell +import Data.List ( intercalate ) + +-- | Double-space a paragraph. +-- +-- Examples: +-- +-- >>> let s1 = "\"Every one of whom?\"" +-- >>> let s2 = "\"Every one of whom do you think?\"" +-- >>> let s3 = "\"I haven't any idea.\"" +-- >>> let paragraph = unlines [s1,s2,s3] +-- >>> putStrLn $ doubleSpace paragraph +-- "Every one of whom?" +-- +-- "Every one of whom do you think?" +-- +-- "I haven't any idea." +-- +doubleSpace :: String -> String +doubleSpace = (intercalate "\n\n") . lines +``` + +## Matching arbitrary output +Any lines containing only three dots (`...`) will match one or more lines with +arbitrary content. For instance, + +```haskell +-- | +-- >>> putStrLn "foo\nbar\nbaz" +-- foo +-- ... +-- baz +``` + +If a line contains three dots and additional content, the three dots will match +anything *within that line*: + +```haskell +-- | +-- >>> putStrLn "foo bar baz" +-- foo ... baz +``` + +## QuickCheck properties + +Haddock has markup support for properties. Doctest can verify properties with +QuickCheck. A simple property looks like this: + +```haskell +-- | +-- prop> \xs -> sort xs == (sort . sort) (xs :: [Int]) +``` + +The lambda abstraction is optional and can be omitted: + +```haskell +-- | +-- prop> sort xs == (sort . sort) (xs :: [Int]) +``` + +A complete example that uses setup code is below: + +```haskell +module Fib where + +-- $setup +-- >>> import Control.Applicative +-- >>> import Test.QuickCheck +-- >>> newtype Small = Small Int deriving Show +-- >>> instance Arbitrary Small where arbitrary = Small . (`mod` 10) <$> arbitrary + +-- | Compute Fibonacci numbers +-- +-- The following property holds: +-- +-- prop> \(Small n) -> fib n == fib (n + 2) - fib (n + 1) +fib :: Int -> Int +fib 0 = 0 +fib 1 = 1 +fib n = fib (n - 1) + fib (n - 2) +``` + +If you see an error like the following, ensure that +[QuickCheck](http://hackage.haskell.org/package/QuickCheck) is visible to +`doctest` (e.g. by passing `--build-depends=QuickCheck` to `cabal repl`). + +```haskell +:39:3: + Not in scope: ‘polyQuickCheck’ + In the splice: $(polyQuickCheck (mkName "doctest_prop")) + +:39:3: + GHC stage restriction: + ‘polyQuickCheck’ is used in a top-level splice or annotation, + and must be imported, not defined locally + In the expression: polyQuickCheck (mkName "doctest_prop") + In the splice: $(polyQuickCheck (mkName "doctest_prop")) +``` + +## Hiding examples from Haddock + +You can put examples into [named chunks][named-chunks], and not refer to them +in the export list. That way they will not be part of the generated Haddock +documentation, but Doctest will still find them. + +```haskell +-- $ +-- >>> 1 + 1 +-- 2 +``` + +[named-chunks]: http://www.haskell.org/haddock/doc/html/ch03s05.html + +## Using GHC extensions + +There's two sets of GHC extensions involved when running Doctest: + +1. The set of GHC extensions that are active when compiling the module code + (excluding the doctest examples). The easiest way to specify these + extensions is through [LANGUAGE pragmas][language-pragma] in your source + files. + +1. The set of GHC extensions that are active when executing the Doctest + examples. (These are not influenced by the LANGUAGE pragmas in the file.) + The recommended way to enable extensions for Doctest examples is to switch + them on like this: + +```haskell +-- | +-- >>> :set -XTupleSections +-- >>> fst' $ (1,) 2 +-- 1 +fst' :: (a, b) -> a +fst' = fst +``` + +Alternatively you can pass any GHC options to Doctest, e.g.: + + doctest -XCPP Foo.hs + +These options will affect both the loading of the module and the execution of +the Doctest examples. + +If you want to omit the information which language extensions are enabled from +the Doctest examples you can use the method described in [Hiding examples from +Haddock](#hiding-examples-from-haddock), e.g.: + +```haskell +-- $ +-- >>> :set -XTupleSections +``` + +[language-pragma]: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/exts/pragmas.html#language-pragma + +# Limitations + + +- Doctests only works on platforms that have support for GHC's `--interactive` mode (`ghci`). + + +- Due to [a GHC bug](https://gitlab.haskell.org/ghc/ghc/-/issues/20670), running + `:set -XTemplateHaskell` within `ghci` may unload any modules that were + specified on the command-line. + + To address this `doctest >= 0.19.0` does two things: + + 1. Doctest always enables `-XTemplateHaskell`. So it is safe to use Template + Haskell in examples without enabling the extension explicitly. + 1. Doctest filters out `-XTemplateHaskell` from single-line `:set`-statements. + So it is still safe to include `:set -XTemplateHaskell` in examples for + documentation purposes. It may just not work as intended in `ghci` due to + that GHC bug. + + Doctest does not filter out `-XTemplateHaskell` from multi-line + `:set`-statements. So if you e.g. use + + ``` + >>> :{ + :set -XTemplateHaskell + :} + ``` + then you are on your own. + + Note that all platforms that support `--interactive` also support + `-XTemplateHaskell`. So this approach does not reduce Doctest's platform + support. + +- Modules that are rejected by `haddock` will not work with `doctest`. This + can mean that `doctest` fails on input that is accepted by GHC (e.g. + [#251](https://github.com/sol/doctest/issues/251)). + +- Doctest works best with UTF-8. If your locale is e.g. `LC_ALL=C`, you may + want to invoke `doctest` with `LC_ALL=C.UTF-8`. + +# Doctest in the wild + +You can find real world examples of `Doctest` being used below: + + * [base Data/Maybe.hs](https://github.com/ghc/ghc/blob/669cbef03c220de43b0f88f2b2238bf3c02ed64c/libraries/base/Data/Maybe.hs#L36-L79) + * [base Data/Functor.hs](https://github.com/ghc/ghc/blob/669cbef03c220de43b0f88f2b2238bf3c02ed64c/libraries/base/Data/Functor.hs#L34-L64) + + +# Development + +Discuss your ideas first, ideally by opening an issue on GitHub. + +Add tests for new features, and make sure that the test suite passes with your +changes. + + cabal build --enable-tests && cabal exec -- cabal test --test-show-details=direct + + +# Contributors + + * Adam Vogt + * Alan Zimmerman + * Alexander Bernauer + * Alexandre Esteves + * Anders Persson + * Andreas Abel + * Ankit Ahuja + * Artyom Kazak + * Edward Kmett + * Gabor Greif + * Hiroki Hattori + * Ignat Insarov + * Jens Petersen + * Joachim Breitner + * John Chee + * João Cristóvão + * Julian Arni + * Kazu Yamamoto + * Leon Schoorl + * Levent Erkok + * Luke Murphy + * Matvey Aksenov + * Michael Orlitzky + * Michael Snoyman + * Mitchell Rosen + * Nick Smallbone + * Nikos Baxevanis + * Oleg Grenrus + * quasicomputational + * Ryan Scott + * Sakari Jokinen + * Simon Hengel + * Sönke Hahn + * Takano Akio + * Tamar Christina + * Veronika Romashkina + +For up-to-date list, query + + git shortlog -s diff --git a/doc/example/fib.cabal b/doc/example/fib.cabal new file mode 100644 index 00000000..5029c9a2 --- /dev/null +++ b/doc/example/fib.cabal @@ -0,0 +1,11 @@ +cabal-version: 1.12 + +name: fib +version: 0.0.0 +build-type: Simple + +library + build-depends: base == 4.* + hs-source-dirs: src + exposed-modules: Fib + default-language: Haskell2010 diff --git a/doc/example/src/Fib.hs b/doc/example/src/Fib.hs new file mode 100644 index 00000000..2a44c73a --- /dev/null +++ b/doc/example/src/Fib.hs @@ -0,0 +1,15 @@ +module Fib where + +-- | Compute Fibonacci numbers +-- +-- Examples: +-- +-- >>> fib 10 +-- 55 +-- +-- >>> fib 5 +-- 5 +fib :: Int -> Int +fib 0 = 0 +fib 1 = 1 +fib n = fib (n - 1) + fib (n - 2) diff --git a/doctest.cabal b/doctest.cabal index 34dc69e5..04170257 100644 --- a/doctest.cabal +++ b/doctest.cabal @@ -7,8 +7,8 @@ cabal-version: 1.12 name: doctest version: 0.20.0 synopsis: Test interactive Haskell examples -description: The doctest program checks examples in source code comments. It is modeled - after doctest for Python (). +description: `doctest` is a small program that checks [examples in Haddock comments](http://www.haskell.org/haddock/doc/html/ch03s08.html#idm140354810775744). + It is similar to the [popular Python module with the same name](https://docs.python.org/3/library/doctest.html). . Documentation is at . category: Testing diff --git a/package.yaml b/package.yaml index f0b27584..f26b84ab 100644 --- a/package.yaml +++ b/package.yaml @@ -2,8 +2,8 @@ name: doctest version: 0.20.0 synopsis: Test interactive Haskell examples description: | - The doctest program checks examples in source code comments. It is modeled - after doctest for Python (). + `doctest` is a small program that checks [examples in Haddock comments](http://www.haskell.org/haddock/doc/html/ch03s08.html#idm140354810775744). + It is similar to the [popular Python module with the same name](https://docs.python.org/3/library/doctest.html). Documentation is at . category: Testing