haskell / mtl

The Monad Transformer Library
http://www.haskell.org/haskellwiki/Monad_Transformers
Other
360 stars 63 forks source link

Add initial docspec setup. #124

Closed andreabedini closed 12 months ago

andreabedini commented 2 years ago

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 commented 2 years ago

I went ahead and converted the remaming examples to docspec format. A couple of observations:

kozross commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

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

andreabedini commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

Gargantuan effort thank you! :smile:

emilypi commented 2 years ago

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

emilypi commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@andreabedini That would be ideal, yes.

andreabedini commented 1 year ago

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

andreabedini commented 1 year ago

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

andreabedini commented 1 year ago

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 commented 12 months ago

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