Add initial docspec setup.

[andreabedini]

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.

[andreabedini]

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 mains into a inline example, adding the expected result to the documentation.
• The Control.Monad.Reader example uses Data.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.

[kozross]

@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.

[andreabedini]

@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!

[kozross]

@andreabedini If you want something that's more general, you can follow my text-ascii setup. It should work everywhere.

[andreabedini]

@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]

@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?

[kozross]

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.

[andreabedini]

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!

[emilypi]

Gargantuan effort thank you! 😄

[emilypi]

If cabal-docspec breaks, i'll pick it up i suppose.

Let's just use @kozross's fork and get homogeneous coverage

[emilypi]

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.

[andreabedini]

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?

[kozross]

@andreabedini That would be ideal, yes.

[andreabedini]

Hey @kozross @emilypi, is there anything else to be done for this PR? Thanks

[andreabedini]

nevermind, they CI fails. I will have a look.

[andreabedini]

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?

[andreabedini]

At this point doc testing should be done with cabal's new code generators feature e.g. https://github.com/gbaz/cabal-doctest-demo