CONTRIBUTION doesn't mention how to build the docs

[k-bx]

Doing the stack test doesn't seem to build the docs, which is slightly inconvenient, since I can't really check if I got them right without Travis.

Would be a nice addition.

[alpmestan]

Right, we use sphinx for this, see this file for some instructions.

I guess it wouldn't hurt to have the contributing document mention this indeed.

Note that if you're a nix enthusiast, nix/shell.nix can also provision the whole sphinx business.

[vcunat]

BTW, with new sphinx the documentation won't build unless you remove a line from config:
https://github.com/haskell-servant/servant/blob/4b247ee801/doc/conf.py#L170

source_parser for 'md' is already registered

[phadej]

That's why we have

https://github.com/haskell-servant/servant/blob/master/doc/requirements.txt

[vcunat]

I see, though ==1.7.5 seems a bit strict requirement to me personally. This way one would end up keeping a dozen versions in each distribution. Docs built fine with 1.7.9 for us and it's a simple one-liner for 1.8.3, but if you prefer it this way...

[phadej]

I use virtualenv (as well as readthedocs) and https://github.com/haskell-servant/servant/blob/master/doc/building-the-docs mentions it. Seems we don't have `html` target in `Makefile` though. Cannot check what's up now. That needs fix indeed. Pipenv isn't supported on readthedocs based on readthedocs/readthedocs.org#3181 Unfortunately I don't know the current best practicies of development in Python, but I'm pretty sure that relying on global installations is not one. (And IIRC there aren't anything like cabal's dependency solver, so sticking to pinned versions (which work) is the best approach). I'd like to read more about Python development practicies though.

…

Sent from my iPhone

On 2 Feb 2019, at 14.18, Vladimír Čunát ***@***.***> wrote: I see, though ==1.7.5 seems a bit strict requirement to me personally. This way one would end up keeping a dozen versions in each distribution. Docs built fine with 1.7.9 for us and it's a simple one-liner for 1.8.3, but if you prefer it this way... — You are receiving this because you commented. Reply to this email directly, view it on GitHub, or mute the thread.

[phadej]

Actually make html works, that Makefile is smart.

Anyway, building-the-docs describes how to build docs, and CONTRIBUTION.md could point to it.

Adding to CI is a bonus of course, it would be nice if haskell-ci could include needed parts from configuration (so we don't need to edit .travis.yml manually).

[vcunat]

For reference, I actually use nix wherever I can, and regression in the nixos.org build farm is what lead me here. I didn't want to mention that specifically, but I see I'm not the first nixer in this thread. With nix we technically can have many versions of packages, but we're trying to restrict that, so I just patched that single line in the nixpkgs official repo...

[phadej]

Wait, does nixpkgs include/build servant's doc/ tutorial or what? Or how the failure there lead you, @vcunat here?

[vcunat]

Yes, our official package is with docs: https://github.com/NixOS/nixpkgs/blob/8ba79e5af/pkgs/development/haskell-modules/configuration-common.nix#L738

[phadej]

@vcunat that's very nice 👍

[domenkozar]

I used to do Python, so I made #1124

[domenkozar]

Can be closed, fixed.

[k-bx]

Thanks!

[k-bx]

Forgot one essential point: does it check the code in docs compiles well? If not – we should mention that in README imo @domenkozar

[alpmestan]

We do check that the tutorial + cookbook recipes compile, in CI.