Big docs & readme update (#98)

The goal is to simplify the docs: to contain only what's this package about so we can keep it up-to-date, no duplicates (rather use cross-references), simpler structure, less talking.

The biggest change in README is the addition of contributing section.

Main changes in docs:

    Menu structure is simpler
    New example for integration with Flux.jl
    Added docs for MapFun and AggregateThenMapFun
    Removed the "Working with images in Julia" page (instead, it is only a tiny section in introduction that refers to JuliaImages docs)
    Removed indices.md


Co-authored-by: Johnny Chen <[email protected]>

Author: barucden

Diff for: README.md

@@ -7,18 +7,33 @@
 [![unittest][action-img]][action-url]
 [![codecov][codecov-img]][codecov-url]
 
-A **fast** Julia library for increasing the number of training
-images by applying various transformations.
-
-Augmentor is a real-time image augmentation library designed to
-render the process of artificial dataset enlargement more
-convenient, less error prone, and easier to reproduce. It offers
-the user the ability to build a *stochastic image-processing
-pipeline* -- which we will also refer to as *augmentation
-pipeline* -- using image operations as building blocks. For our
-purposes, an augmentation pipeline can be understood as a
-sequence of operations for which the parameters can (but need
-not) be random variables.
+**Augmentor.jl** is a *fast* Julia library designed to make the process of
+image augmentation more convenient, less error-prone, and easier to reproduce.
+It offers a simple way to build flexible **augmentation pipelines**. For our
+purposes, an augmentation pipeline can be understood as a sequence of
+operations for which the parameters can (but need not) be random variables.
+
+When augmenting, Augmentor.jl uses multiple heuristics to generate efficient
+tailor-made code for the concrete user-specified augmentation pipeline. In
+particular, Augmentor tries to avoid the need for any intermediate images and
+aims to compute the output image directly from the input in one single pass.
+
+## Overview
+
+Augmentor.jl provides many augmentation operations such as rotations, flipping,
+blurring, and more. See the
+[documentation](https://evizero.github.io/Augmentor.jl/stable/operations/) for
+the complete list of available operations.
+
+The package uses the `|>` operator to **compose** operations into a pipeline.
+
+Prepared pipelines are applied to images by calling one of the higher-level
+functions: `augment`, `augment!`, or `augmentbatch!`.
+
+The full documentation is available at
+[evizero.github.io/Augmentor.jl/](https://evizero.github.io/Augmentor.jl/).
+
+## Example
 
 ```julia
 julia> pl = ElasticDistortion(6, scale=0.3, border=true) |>
@@ -38,44 +53,33 @@ julia> augment(img, pl)
 
 ![](https://evizero.github.io/Augmentor.jl/dev/mnist_preview.gif)
 
-The Julia version of Augmentor is engineered specifically for
-high performance applications. It makes use of multiple
-heuristics to generate efficient tailor-made code for the
-concrete user-specified augmentation pipeline. In particular
-Augmentor tries to avoid the need for any intermediate images,
-but instead aims to compute the output image directly from the
-input in one single pass.
-
-**Augmentor.jl** is the [Julia](http://julialang.org)
-implementation for Augmentor. The Python version of the same name
-is available [here](https://github.com/mdbloice/Augmentor).
+For more examples, see [the documentation](https://evizero.github.io/Augmentor.jl/).
 
-## Package Overview
+## Contributing
 
-Augmentor.jl provides:
+Contributions are greatly appreciated!
 
-* predefined augmentation operations, e.g., `FlipX`
-* `|>` operator to compose operations into a pipeline
-* higher-lvel functions (`augment`, `augment!` and `augmentbatch!`) that works on a pipeline and image(s).
-
-Check the [documentation](https://evizero.github.io/Augmentor.jl/stable/operations/) for a full list of operations.
+To report a potential **bug** or propose a **new feature**, please file a *new
+issue*. *Pull requests* are always welcome. However, to make sure the PR gets
+accepted, it is generally preferred when it follows a particular issue to which
+it refers.
 
 ## Citing Augmentor
 
-If you use Augmentor for academic research and wish to cite it,
-please use the following paper.
+If you use Augmentor for academic research and wish to cite it, please use the
+following paper.
 
-Marcus D. Bloice, Christof Stocker, and Andreas Holzinger,
-*Augmentor: An Image Augmentation Library for Machine Learning*,
-arXiv preprint **arXiv:1708.04680**,
+Marcus D. Bloice, Christof Stocker, and Andreas Holzinger, *Augmentor: An Image
+Augmentation Library for Machine Learning*, arXiv preprint **arXiv:1708.04680**,
 <https://arxiv.org/abs/1708.04680>, 2017.
 
 ## Acknowledgments
 
-This package makes heavy use of the following packages in order
-to provide it's main functionality. To see at full list of
-utilized packages, please take a look at the [REQUIRE](./REQUIRE)
-file.
+This package is inspired by a Python library of the same name available at
+[github.com/mdbloice/Augmentor](https://github.com/mdbloice/Augmentor).
+
+To provide most of the operations, Augmentor.jl makes heavy use of many
+packages. To name a few:
 
 - [FugroRoames/CoordinateTransformations.jl](https://github.com/FugroRoames/CoordinateTransformations.jl)
 - [JuliaImages/ImageTransformations.jl](https://github.com/JuliaImages/ImageTransformations.jl)

Diff for: docs/Project.toml

@@ -3,12 +3,15 @@ Augmentor = "02898b10-1f73-11ea-317c-6393d7073e15"
 DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
+Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 ImageDraw = "4381153b-2b60-58ae-a1ba-fd683676385f"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 ImageShow = "4e3cecfd-b093-5904-9786-8bbb286a6a31"
 Images = "916415d5-f1e6-5110-898d-aaa5f9f070e0"
+MLDataUtils = "cc2ba9b6-d476-5e6d-8eaf-a92d5412d41d"
 MLDatasets = "eb30cadb-4394-5ae3-aed4-317e484a6458"
+MappedArrays = "dbb5928d-eab1-5f90-85c2-b9b0edb7c900"
 MosaicViews = "e94cdb99-869f-56ef-bcf0-1ae2bcbe0389"
 OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 PaddedViews = "5432bcbf-9aad-5242-b902-cca2824c8663"

Diff for: docs/examples/examples/assets/mnist_elastic.gif

@@ -15,47 +15,53 @@ ENV["DATADEPS_ALWAYS_ACCEPT"] = true # MLDatasets
 
 op_templates, op_theme = cardtheme("grid")
 operations, operations_cb = makedemos("operations", op_templates)
-examples_templates, examples_theme = cardtheme("list")
-examples, examples_cb = makedemos("examples", examples_templates)
 
 format = Documenter.HTML(edit_link = "master",
                          prettyurls = get(ENV, "CI", nothing) == "true",
                          assets = [
                              joinpath("assets", "favicon.ico"),
                              joinpath("assets", "style.css"),
-                             op_theme,
-                             examples_theme
+                             op_theme
                         ]
 )
 
+About = "Introduction" => "index.md"
+
+GettingStarted = "gettingstarted.md"
+
+UserGuide = "User's guide" => [
+        "interface.md",
+        operations
+    ]
+
+DevGuide = "Developer's guide" => [
+        "wrappers.md"
+    ]
+
+Examples = "Examples" => [
+        "examples/flux.md"
+    ]
+
+License = "License" => "license.md"
+
+PAGES = [
+    About,
+    GettingStarted,
+    UserGuide,
+    DevGuide,
+    Examples,
+    License
+    ]
+
 makedocs(
     modules = [Augmentor],
     sitename = "Augmentor.jl",
     authors = "Christof Stocker",
-    # linkcheck = true,
     format = format,
-    pages = [
-        "Home" => "index.md",
-        "gettingstarted.md",
-        "Introduction and Motivation" => [
-            "background.md",
-            "images.md",
-        ],
-        "User's Guide" => [
-            "interface.md",
-            operations
-        ],
-        "Developer's Guide" => [
-            "wrappers.md"
-        ],
-        "Tutorials" => examples,
-        hide("Indices" => "indices.md"),
-        "LICENSE.md",
-    ],
-    # doctest=:fix, # used to fix outdated doctest
+    checkdocs = :exports,
+    pages = PAGES
 )
 
 operations_cb()
-examples_cb()
 
 deploydocs(repo = "github.com/Evizero/Augmentor.jl.git")

Diff for: docs/examples/examples/mnist_elastic.md

@@ -1,6 +1,7 @@
 {
     "order":[
         "layout.jl",
-        "utilities.jl"
+        "utilities.jl",
+        "higherorder.jl"
     ]
 }

Diff for: docs/examples/index.md

@@ -0,0 +1,28 @@
+# ---
+# title: Higher-order functions
+# description: a set of helper opeartions that allow applying any function
+# ---
+
+# These operations are useful to perform an operation that is not explicitly
+# defined in Augmentor.
+
+using Augmentor
+using Random
+using Statistics: mean
+
+Random.seed!(1337)
+
+DecreaseContrast = MapFun(pixel -> pixel / 2)
+IncreaseBrightness = AggregateThenMapFun(img -> mean(img),
+                                         (pixel, M) -> pixel + M / 5)
+
+img_in = testpattern(RGB, ratio=0.5)
+img_out = augment(img_in, DecreaseContrast |> IncreaseBrightness)
+
+# ## References
+
+#md # ```@docs
+#md # MapFun
+#md # AggregateThenMapFun
+#md # ```
+

Diff for: docs/make.jl

@@ -1,7 +1,7 @@
 # ---
 # title: Composition utilities
 # cover: utilities.gif
-# description: a set of helper opeartions that may be useful when compositing more complex augmentation workflow
+# description: a set of helper operations that may be useful when compositing more complex augmentation workflow
 # ---
 
 # Aside from "true" operations that specify some kind of transformation, there are also a couple of