mtl
mtl copied to clipboard
Add initial docspec setup.
This adds the setup required to run doc-testing using cabal-docspec, developed by @phadej.
This is the same setup that the the "kmettverse" uses (e.g. the comonad package).
It also starts converting existing documentation to docspecs, i.e. the Control.Monad.Except module.
I went ahead and converted the remaming examples to docspec format. A couple of observations:
- cabal-docspec works by feeding code to ghci, this means that declarations have to be entered one at the tiem and in the right order. I had to slightly rework the
Contol.Monad.Reader
example to get it work. - Where possible, I turned top level
main
s into a inline example, adding the expected result to the documentation. - The
Control.Monad.Reader
example usesData.Map
from containers. cabal-docspec reuses the build plan built by cabal and containers is not a build dependency of mtl, so it would not be available to cabal-docspec. As per the cabal-docspec documentation, to get this to work I have added a line to cabal.project to include containers in the build plan, and told cabal-docspec to add that package to ghci.
@andreabedini I'm very happy that someone has undertaken this: it looks great! However, we need to ensure that this passes CI, and it currently fails on macOS. I also suspect it'll fail on Windows.
@kozross thanks. I have been too liberal in copying comonad’s setup without realising how specific that environment is. I’ll get this to work on Monday!
@andreabedini If you want something that's more general, you can follow my text-ascii
setup. It should work everywhere.
@andreabedini If you want something that's more general, you can follow my
text-ascii
setup. It should work everywhere.
oh, I like your setup! I wish cabal-docspec was on Hackage (or had binaries for macOS and Windows).
@andreabedini If you want something that's more general, you can follow my
text-ascii
setup. It should work everywhere.
I like your setup, but after thinking a bit about it, I belive we should only run docspec on the platforms we have a binary release for, which AFAIK is only Linux.
The reason is not adding complexity to the mtl CI. I would not want mtl
CI to become a CI for cabal-docspec
. E.g. Oleg uses ghc 8.10.4 on his repository. What if 9.2 breaks cabal-docspec?
I'm really torn about this. On the one hand, you are absolutely right, but on the other hand, I feel this is basically relegating other platforms to second-class status in the CI, which I oppose.
I'm really torn about this. On the one hand, you are absolutely right, but on the other hand, I feel this is basically relegating other platforms to second-class status in the CI, which I oppose.
<3 I am 1000% with you on this! Perhaps we should direct our efforts to support Oleg?
Also, docspec on linux vs no docspec anywhere is still a step forward!
Gargantuan effort thank you! :smile:
If cabal-docspec breaks, i'll pick it up i suppose.
I like your setup, but after thinking a bit about it, I belive we should only run docspec on the platforms we have a binary release for, which AFAIK is only Linux.
This doesn't make sense to me. What about having a binary privileges it to be doctested, when the doctests are part of the test contract for every distribution on every platform? Koz already has a fork that covers mac and windows. We should be committing to doctests as a supplement to the unit and property tests we already do, not as coverage for any binary, and further, we don't cut binaries, we cut archives with source.
This doesn't make sense to me.
That's ok. I guess my real intent was to delimit as much as possible what's on mtl's team plate and what is not. Using a fork of cabal-extras works fine and it allows us to cover all platforms, which is great, but also brings in more work on @kozross :-) Reading back what I wrote I think by "having a binary release for" I meant to say "someone else is responsible for".
I am happy with whatever way you decide to go. Doc-testing is the goal here, not the details of how we install the tool.
Do you want me to update this PR following @kozross text-ascii
setup?
@andreabedini That would be ideal, yes.
Hey @kozross @emilypi, is there anything else to be done for this PR? Thanks
nevermind, they CI fails. I will have a look.
right, cabal-docspec fails to compile on ghc 9.4.1, which is the kind of issues I was expecting in my previous comment. I guess I can just disable doc testing on ghc 9.4.1?