From 142c511a3e900cb4e4a1b4f199ea9b215f5c0946 Mon Sep 17 00:00:00 2001
From: George Datseris <datseris.george@gmail.com>
Date: Tue, 9 Oct 2018 13:19:04 +0200
Subject: [PATCH] add include pre-processing example (#35)

---
 docs/src/customprocessing.md | 51 ++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/src/customprocessing.md b/docs/src/customprocessing.md
index 27906ab..756e3cf 100644
--- a/docs/src/customprocessing.md
+++ b/docs/src/customprocessing.md
@@ -22,6 +22,7 @@ is given the content `String` just before writing it to the output file, but for
 notebook output `postprocess` is given the dictionary representing the notebook,
 since, in general, this is more useful.
 
+### Example: Adding current date
 As an example, lets say we want to splice the date of generation into the output.
 We could of course update our source file before generating the docs, but we could
 instead use a `preprocess` function that splices the date into the source for us.
@@ -45,3 +46,53 @@ now simply give this function to the generator, for example:
 ```julia
 Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
 ```
+
+### Example: Replacing `include` calls with included code
+Let's say that we have some individual example files `file1, file2, ...` etc.
+that are _runnable_ and also following the style of Literate. These files could be for example used in the test suite of your package.
+
+We want to group them all into a single page in our documentation, but we
+do not want to copy paste the content of `file1, ...` for robustness: the files are included in the test suite and some changes may occur to them. We want these changes to also be reflected in the documentation.
+
+A very easy way to do this is using `preprocess` to interchange `include` statements with file content. First, create a runnable `.jl` following the format of Literate
+```julia
+# # Replace includes
+# This is an example to replace `include` calls with the actual file content.
+
+include("file1.jl")
+
+# Cool, we just saw the result of the above code snippet. Here is one more:
+
+include("file2.jl")
+```
+
+Let's say we have saved this file as `examples.jl`.
+Then, you want to properly define a pre-processing function:
+
+```julia
+function replace_includes(str)
+
+    included = ["file1.jl", "file2.jl"]
+
+    # Here the path loads the files from their proper directory,
+    # which may not be the directory of the `examples.jl` file!
+    path = "directory/to/example/files/"
+
+    for ex in included
+        content = read(path*ex, String)
+        str = replace(str, "include(\"$(ex)\")" => content)
+    end
+    return str
+end
+```
+(of course replace `included` with your respective files)
+
+Finally, you simply pass this function to e.g. [`Literate.markdown`](@ref) as
+```julia
+Literate.markdown("examples.jl", "path/to/save/markdown";
+                  name = "markdown_file_name", preprocess = replace_includes)
+```
+and you will see that in the final output file (here `markdown_file_name.md`) the `include`
+statements are replaced with the actual code to be included!
+
+This approach is used for example in the documentation of the Julia package [`TimeseriesPrediction`](https://github.com/JuliaDynamics/TimeseriesPrediction.jl), see [here](https://github.com/JuliaDynamics/DynamicalSystems.jl/blob/master/docs/src/tsprediction/stexamples.jl) and [here for the generating script](https://github.com/JuliaDynamics/DynamicalSystems.jl/blob/master/docs/make.jl#L11-L29)