Improve docs for Conv etc.

[mcabbott]

This re-writes the docstrings for the convolutional layers, as I thought they were confusing and occasionally misleading. (I guess they grew organically over time.) It adds many examples as these often seem clearer than words; hopefully they will be run as doctests but I'm not entirely sure.

No functional changes.

One small printing change, that MaxPool((5, 5), pad = 2, stride = (5, 5)) prints like this, not pad = (2, 2, 2, 2). Perhaps that should be made still less verbose. Or Conv more verbose?

[DrChainsaw]

Worth pointing out that ConvTranspose is the odd bird in the conv-gang w.r.t SamePad as it has the relationship outsize = insize * stride.

[CarloLucibello]

This PR is a great improvement, thanks! It's ready to be merged?

[mcabbott]

I have one more commit, to simplify printing of MaxPool by hiding strides & padding when they have their default values. May as well, right?

[CarloLucibello]

sure

[CarloLucibello]

I have one more commit, to simplify printing of MaxPool by hiding strides & padding when they have their default values. May as well, right?

actually I'm not sure about this, but I think it's ok since the defaults are so commonly used and intuitive for this layer

[mcabbott]

Can un-do if you think it's better. But otherwise I am done here.

At the moment Conv doesn't print padding/stride etc. at all. But if we want to make that verbose too, so that copying the printed output gives the same dimensions, then perhaps that's another PR.

[CarloLucibello]

look's fine like this, thanks

bors r+

[bors]

Build succeeded:

• ci/gitlab/gitlab.com

[mcabbott]

Note to self: Only the docstring for the first method of Conv seems to show up here:

https://fluxml.ai/Flux.jl/dev/models/layers/#Flux.Conv

According to https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@docs-block one can give signatures, but they must be exact. So we should fix that once the signature has settled down.