add cabal-docspec to flake dependencies and include examples for most symbols

[MMesch]

This adds cabal-docspec to the flake dependencies to start addressing https://github.com/VinylRecords/Vinyl/blob/master/vinyl.cabal#L96.

It's currently taken from the Nix user repo because it is not yet on hackage or nixpkgs.

Run with

nix develop
cabal-docspec

This is the current output summary:

[   0.60765] doctest.summary: 
Total:        77; Tried:   36; Skipped:   41; Success:   30; Errors:    6; Failures    0
Examples:     75; Tried:   34; Skipped:   41; Success:   28; Errors:    6; Failures    0
Setup:         2; Tried:    2; Skipped:    0; Success:    2; Errors:    0; Failures    0

I plan fixing the errors in subsequent PRs, but I thought it'd be nice to have cabal-docspec in already before because there seems to be no possibility to run doctests at the moment whatsoever. And also to keep PR size small.

[MMesch]

I am working now on this branch but maybe it'd be better to split the PR up. @acowley let me know what you would prefer. Also, I really don't know what the best solution is to make the Tutorial pass doctests without adding a global dependency on singletons which is a bit annoying.

[acowley]

How would you split it up?

[MMesch]

There are some simple changes such as fixing or adding doctests. And there are some like the singletons version bounds that may be more complex.

I pushed a new version with open version bounds but I'm unsure how to sustainably resolve this issue because it's a pity to add a dependency on the main library just for the tutorial. Maybe best would be to keep the tutorial just in tests and then link to it from the haddock page?

[acowley]

That sounds reasonable regarding singletons. I agree that we should avoid making it a dependency of the library if possible.

[MMesch]

@acowley I think I managed to run all examples, including the existing Tutorial through cabal-docspec without adding singletons as a library dependency (it is added through a dummy doctests target and then exposed through an extra field).

I think we could try activating it in CI but that's a bit difficult for me to do without access to it. In theory you should be able to run it with cabal-docspec in the base folder after building the code with cabal build all --enable-tests.

[MMesch]

@acowley , I investigated this a bit and unfortunately it seems more complex to get a cabal-docspec binary for Mac and Windows than what I have time for right now.

Wouldn't it be sufficient to just run the doctests on the Linux CI? As opposed to the build, I don't think testing the docs cross platform adds much extra value. And for development on mac, maybe the cabal-docspec Docker container works until there is a proper binary available?

[acowley]

Yes, running only in CI is definitely an option. I was going to take a look at a from source build of cabal-docspec, did anything in particular not work out when you looked at it or was it just a big pain?

[MMesch]

Nothing in particular except for various general comments in the cabal-extras repo on the build process that may indicate complexity. But it's probably more because I'm not super experienced with the Nix Haskell infra, I fear I can't really debug any Macos or Windows builds, and I don't have enough headspace at the moment to dive into that 🙄. I want to mostly add documentation to vinyl and frames and maybe make some smaller improvements since I tried using those more actively recently.

I also wonder what the proper way forward is so that we don't duplicate effort that should find it's place upstream. But considering all options (eg hackage doesn't seem to be in sight), I think writing a cross platform flake for cabal-extras seems like the most reasonable thing to do.

[acowley]

Wow, cabal-extras is pretty deeply idiosyncratic. I'm not sure if it's worth trying to make its individual parts look more like normal packages. Definitely open to the CI-only solution.