Documentation reorganization - a suggestion

[cormullion]

This PR comprises a suggested reorganization of the documentation. My approach is probably reasonably similar to the Divio style - at least, try to keep different types of information separate, so that novices, casual users, experienced users, and package developers don't trip over material not meant for them. (I think this is probably the opposite of Images' current approach (judging from this RFC issue.)

The main thing was just to add some hierarchy to the manual, then to move as much stuff out of the docstrings as possible (cf my previous pet gripe, all that LaTeX). 😂

(I'm not too sure how you'd preview this...)

[codecov[bot]]

Codecov Report

Patch coverage: 93.75% and no project coverage change.

Comparison is base (baedd6d) 94.34% compared to head (42adb97) 94.34%.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## master #256 +/- ## ======================================= Coverage 94.34% 94.34% ======================================= Files 13 13 Lines 1697 1697 ======================================= Hits 1601 1601 Misses 96 96 ``` | [Impacted Files](https://app.codecov.io/gh/JuliaImages/ImageFiltering.jl/pull/256?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaImages) | Coverage Δ | | |---|---|---| | [src/extrema.jl](https://app.codecov.io/gh/JuliaImages/ImageFiltering.jl/pull/256?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaImages#diff-c3JjL2V4dHJlbWEuamw=) | `100.00% <ø> (ø)` | | | [src/kernel.jl](https://app.codecov.io/gh/JuliaImages/ImageFiltering.jl/pull/256?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaImages#diff-c3JjL2tlcm5lbC5qbA==) | `100.00% <ø> (ø)` | | | [src/mapwindow.jl](https://app.codecov.io/gh/JuliaImages/ImageFiltering.jl/pull/256?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaImages#diff-c3JjL21hcHdpbmRvdy5qbA==) | `87.30% <84.09%> (ø)` | | | [src/border.jl](https://app.codecov.io/gh/JuliaImages/ImageFiltering.jl/pull/256?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaImages#diff-c3JjL2JvcmRlci5qbA==) | `94.56% <95.65%> (ø)` | | | [src/imfilter.jl](https://app.codecov.io/gh/JuliaImages/ImageFiltering.jl/pull/256?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaImages#diff-c3JjL2ltZmlsdGVyLmps) | `96.74% <98.64%> (ø)` | | | [src/specialty.jl](https://app.codecov.io/gh/JuliaImages/ImageFiltering.jl/pull/256?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=JuliaImages#diff-c3JjL3NwZWNpYWx0eS5qbA==) | `100.00% <100.00%> (ø)` | |

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Do you have feedback about the report comment? Let us know in this issue.

[zygmuntszpak]

Many thanks for taking on this big task. I managed to build the documentation locally without any issues. There's obviously a lot to read through, but my first impression is that people will find the REPL experience much more pleasant now that you moved the LaTeX out into separate documents. The tutorial you wrote is also really nice, and in general the layout of the documentation feels like a great improvement.

One thing I notice is that imgradients now has no more meaningful docstring. It might be worth retaining some parts of the previous docstring.

[ashwani-rathee]

Can we please move this forward?It would be great to get this done, issa common gripe 😓

[timholy]

Can we please move this forward?It would be great to get this done, issa common gripe 😓

Best way to make that happen is to give it a thorough review! But you could wait until my comments above are addressed.

[timholy]

(I'm not too sure how you'd preview this...)

Would adding push_preview=true fix that? https://documenter.juliadocs.org/stable/lib/public/#Documenter.deploydocs

[cormullion]

@timholy Thanks so much for the comments and review, and for taking the time... I confess I don't understand the fine details of the package, but perhaps the structure of the docs is a bit better now, and in the future will allow people to add more information in the right place.

[timholy]

When I'm back from travels I'll build this locally and give it a read-through; assuming nothing serious comes up I'll merge as-is and we can fix minor problems later. Or if anyone else wants to build it and do that for me, just let me know the verdict and we can merge more quickly.

[timholy]

I built it locally, and it looks awesome. Thanks ever so much, @cormullion! A huge contribution!

[cormullion]

Did these docs ever get released?