Add a note about how to limit display output in notebooks, fixes #61.

docs/Manifest.toml

@@ -285,9 +285,9 @@ uuid = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [[StatsBase]]
 deps = ["DataAPI", "DataStructures", "LinearAlgebra", "Missings", "Printf", "Random", "SortingAlgorithms", "SparseArrays", "Statistics"]
-git-tree-sha1 = "be5c7d45daa449d12868f4466dbf5882242cf2d9"
+git-tree-sha1 = "19bfcb46245f69ff4013b3df3b977a289852c3a1"
 uuid = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
-version = "0.32.1"
+version = "0.32.2"
 
 [[Test]]
 deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]

docs/make.jl

@@ -58,6 +58,7 @@ makedocs(
         "outputformats.md",
         "customprocessing.md",
         "documenter.md",
+        "tips.md",
         "generated/example.md"]
 )
 

docs/src/tips.md

@@ -0,0 +1,41 @@
+# [**7.** Tips and Tricks](@id tips-and-tricks)
+
+This section lists some tips and tricks that might be useful for using
+Literate.
+
+### [Filesize of generated notebooks](@id notebook-filesize)
+
+When Literate executes a notebook the return value, i.e. the result of the
+last Julia expression in each cell is captured. By default Literate generates
+multiple renderings of the result in different output formats or
+[MIME](https://en.wikipedia.org/wiki/MIME)s, just like
+[IJulia.jl](https://github.com/JuliaLang/IJulia.jl) does. All of these renderings
+are embedded in the notebook and it is up to the notebook frontend viewer to select
+the most appropriate format to show to the user.
+
+A common example is images, which can often be displayed in multiple formats, e.g. PNG
+(`image/png`), SVG (`image/svg+xml`) and HTML (`text/html`). As a result, the filesize of
+the generated notebook can become large.
+
+In order to remedy this you can use the clever Julia package
+[`DisplayAs`](https://github.com/tkf/DisplayAs.jl) to limit the output capabilities of
+and object. For example, to "force" and image to be captures as `image/png` only,
+you can use
+
+```julia
+import DisplayAs
+img = plot(...)
+img = DisplayAs.PNG(img)
+```
+
+This can save some memory, since the image is never captured in e.g. SVG or
+HTML formats.
+
+!!! note
+    It is best to always let the object be showable as `text/plain`. This can be achieved
+    by nested calls to `DisplayAs` output types. For example, to limit an image `img` to
+    be showable as just `image/png` and `text/plain` you can use
+    ```julia
+    img = plot(...)
+    img = DisplayAs.Text(DisplayAs.Text(img))
+    ```

examples/example.jl

@@ -1,4 +1,4 @@
-# # **7.** Example
+# # **8.** Example
 #
 #md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/generated/example.ipynb)
 #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/generated/example.ipynb)