From 0105ffe273ecd1868b220570adfd1a93844cd424 Mon Sep 17 00:00:00 2001
From: Fredrik Ekre <fredrik.ekre@chalmers.se>
Date: Wed, 2 May 2018 16:24:09 +0200
Subject: [PATCH] use a better example, show real notebook (#5)

---
 docs/make.jl              | 17 +++++++++
 docs/src/outputformats.jl | 12 +++++++
 docs/src/outputformats.md | 76 ++++++++++-----------------------------
 3 files changed, 47 insertions(+), 58 deletions(-)
 create mode 100644 docs/src/outputformats.jl

diff --git a/docs/make.jl b/docs/make.jl
index 982e735..e053dd7 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -15,6 +15,23 @@ Literate.markdown(EXAMPLE, OUTPUT, preprocess = preprocess)
 Literate.notebook(EXAMPLE, OUTPUT, preprocess = preprocess)
 Literate.script(EXAMPLE, OUTPUT, preprocess = preprocess)
 
+# generate the example notebook for the documentation, keep in sync with outputformats.md
+Literate.markdown(joinpath(@__DIR__, "src/outputformats.jl"), OUTPUT; credit = false, name = "name")
+Literate.notebook(joinpath(@__DIR__, "src/outputformats.jl"), OUTPUT, name = "notebook")
+Literate.script(joinpath(@__DIR__, "src/outputformats.jl"), OUTPUT, credit = false)
+
+# replace the link in outputformats.md
+travis_tag = get(ENV, "TRAVIS_TAG", "")
+folder = isempty(travis_tag) ? "latest" : travis_tag
+url = "https://nbviewer.jupyter.org/github/fredrikekre/Literate.jl/blob/gh-pages/$(folder)/"
+if get(ENV, "HAS_JOSH_K_SEAL_OF_APPROVAL", "") == "true"
+    str = read(joinpath(@__DIR__, "src/outputformats.md"), String)
+    @show url
+    str = replace(str, "[notebook.ipynb](generated/notebook.ipynb)." => "[notebook.ipynb]($(url)generated/notebook.ipynb).")
+    write(joinpath(@__DIR__, "src/outputformats.md"), str)
+end
+
+
 makedocs(
     modules = [Literate],
     format = :html,
diff --git a/docs/src/outputformats.jl b/docs/src/outputformats.jl
new file mode 100644
index 0000000..4fbfd71
--- /dev/null
+++ b/docs/src/outputformats.jl
@@ -0,0 +1,12 @@
+#' # Rational numbers
+#'
+#' In julia rational numbers can be constructed with the `//` operator.
+#' Lets define two rational numbers, `x` and `y`:
+
+x = 1//3
+#-
+y = 2//5
+
+#' When adding `x` and `y` together we obtain a new rational number:
+
+z = x + y
diff --git a/docs/src/outputformats.md b/docs/src/outputformats.md
index 6b04aff..500df03 100644
--- a/docs/src/outputformats.md
+++ b/docs/src/outputformats.md
@@ -3,19 +3,8 @@
 When the source is parsed, and have been processed it is time to render the output.
 We will consider the following source snippet:
 
-```julia
-#' # Rational numbers
-#'
-#' In julia rational numbers can be constructed with the `//` operator.
-#' Lets define two rational numbers, `x` and `y`:
-
-x = 1//3
-#-
-y = 2//5
-
-#' When adding `x` and `y` together we obtain a new rational number:
-
-z = x + y
+```@eval
+Markdown.parse("```julia\n" * rstrip(read("outputformats.jl", String)) * "\n```")
 ```
 
 and see how this is rendered in each of the output formats.
@@ -24,29 +13,18 @@ and see how this is rendered in each of the output formats.
 
 The (default) markdown output of the source snippet above is as follows
 
-````markdown
-# Rational numbers
-
-In julia rational numbers can be constructed with the `//` operator.
-Lets define two rational numbers, `x` and `y`:
-
-```@example name
-x = 1//3
-```
-
-```@example name
-y = 2//5
-```
-
-When adding `x` and `y` together we obtain a new rational number:
-
-```@example name
-z = x + y
+```@eval
+file = joinpath(@__DIR__,  "src/generated/name.md")
+str = "````markdown\n" * rstrip(read(file, String)) * "\n````"
+rm(file)
+Markdown.parse(str)
 ```
-````
 
 We note that lines starting with `#'` is printed as regular markdown,
-and the code lines have been wrapped in `@example` blocks.
+and the code lines have been wrapped in `@example` blocks. We also note that
+an `@meta` block have been added, that sets the `EditURL` variable. This is used
+by Documenter to redirect the "Edit on GitHub" link for the page,
+see [Interaction with Documenter](@ref).
 
 Some of the output rendering can be controlled with keyword arguments to
 [`Literate.markdown`](@ref):
@@ -57,25 +35,8 @@ Literate.markdown
 
 ## [**4.2.** Notebook Output](@id Notebook-Output)
 
-The (default) notebook output of the source snippet above is as follows
-
-```
-        │ # Rational numbers
-        │
-        │ In julia rational numbers can be constructed with the `//` operator.
-        │ Lets define two rational numbers, `x` and `y`:
-
-In[1]:  │ x = 1//3
-Out[1]: │ 1//3
-
-In[2]:  │ y = 2//5
-Out[2]: │ 2//5
-
-        │ When adding `x` and `y` together we obtain a new rational number:
-
-In[3]:  │ z = x + y
-Out[3]: │ 11/15
-```
+The (default) notebook output of the source snippet can be seen here:
+[notebook.ipynb](generated/notebook.ipynb).
 
 We note that lines starting with `#'` is put in markdown cells,
 and the code lines have been put in code cells. By default the notebook
@@ -93,12 +54,11 @@ Literate.notebook
 
 The (default) script output of the source snippet above is as follows
 
-```julia
-x = 1//3
-
-y = 2//5
-
-z = x + y
+```@eval
+file = joinpath(@__DIR__,  "src/generated/outputformats.jl")
+str = "```julia\n" * rstrip(read(file, String)) * "\n```"
+rm(file)
+Markdown.parse(str)
 ```
 
 We note that lines starting with `#'` are removed and only the