Rework docstrings

[t-bltg]

This PR automates docstring generation for arguments, function signatures, and README.md. Fix #45 ?

Rationale:

• lots of arguments are duplicated across interfaces, with very similar signatures.
• by automating this we can check descriptions: should start with a lowercase letter, sentences should end with a dot, ...
• removing about 200+ lines of docstring code (with duplicates) for the same result.
• simplifies maintenance for changes ( auto-generated README.md (default keywords), and gen_imgs.jl file for updating the examples).

The auto-generated README.md can be seen here, it should be rendered close to the existing one. It didn't want to pull in Documenter.jl, I'm just using Markdown from the stdlib to generate it dynamically.

Other changes:

• simplify sentences by aiming single phrases, and reduce string lengths (for synthetic display in REPL).
• follow Markdown syntax, as advised in Julia's documentation.
• unifies func(args..., kwargs...) syntax.
• transform z -> A in heatmap.jl, sinceA reflects a matrix structure by convention.

I've carefully inspected the results of help?> <function> where function is scatterplot, Plot, barplot, heatmap, ... against master and this is either equivalent of way better structured, since the arguments now follow a fixed order. We can fine tune each function arguments by giving desc, add, or remove keywords for the added arguments or signature functions.

• generate descriptions
• generate signatures
• generate README.md automatically
• generate examples automatically

I'm guessing that the runtime generation of docstrings only affects precompilation of Unicodeplots and not load time, but I'm not sure of that.

Unexpected, and this looks bad:
PR

julia> @time using UnicodePlots
  1.353077 seconds (3.25 M allocations: 231.825 MiB, 5.12% compilation time)

master

julia> @time using UnicodePlots
  0.395560 seconds (701.22 k allocations: 41.487 MiB, 17.54% compilation time)

@johnnychen94, do you have any obvious idea why this happens ?

EDIT: sorry for the noise, the increased load time was just the effect of adding Contour dependency and thus loading StaticArrays.

[codecov-commenter]

Codecov Report

Merging #206 (42f5f06) into master (d4a63d2) will increase coverage by 0.00%.
The diff coverage is 96.66%.

@@           Coverage Diff           @@
##           master     #206   +/-   ##
=======================================
  Coverage   99.57%   99.58%           
=======================================
  Files          24       25    +1     
  Lines        1180     1200   +20     
=======================================
+ Hits         1175     1195   +20     
  Misses          5        5           

Impacted Files	Coverage Δ
src/canvas/lookupcanvas.jl	100.00% <ø> (ø)
src/colormaps.jl	100.00% <ø> (ø)
src/common.jl	100.00% <ø> (ø)
src/interface/barplot.jl	100.00% <ø> (ø)
src/interface/boxplot.jl	100.00% <ø> (ø)
src/interface/contourplot.jl	100.00% <ø> (+4.76%)	⬆️
src/interface/densityplot.jl	100.00% <ø> (ø)
src/interface/histogram.jl	100.00% <ø> (ø)
src/interface/lineplot.jl	97.10% <ø> (ø)
src/interface/scatterplot.jl	100.00% <ø> (ø)
... and 9 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d4a63d2...42f5f06. Read the comment docs.

[t-bltg]

@johnnychen94, just to let you know that I think the PR is ready for review (nothing urgent though 😉 )

[johnnychen94]

neat!