binder links (#57)

* Add at__BINDER_ROOT_URL__ macro to expand to a binder link, fixes #46.
fredrikekre · Apr 5, 2019 · fa64dcd · fa64dcd
1 parent 28dad19
commit fa64dcd
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 23 deletions.
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
@@ -15,9 +15,9 @@ version = "0.9.5"
 
 [[Compat]]
 deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"]
-git-tree-sha1 = "ec61a16eed883ad0cfa002d7489b3ce6d039bb9a"
+git-tree-sha1 = "84aa74986c5b9b898b0d1acaf3258741ee64754f"
 uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
-version = "1.4.0"
+version = "2.1.0"
 
 [[Contour]]
 deps = ["LinearAlgebra", "StaticArrays", "Test"]
@@ -45,15 +45,17 @@ uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 
 [[DocStringExtensions]]
 deps = ["LibGit2", "Markdown", "Pkg", "Test"]
-git-tree-sha1 = "1df01539a1c952cef21f2d2d1c092c2bcf0177d7"
+git-tree-sha1 = "4d30e889c9f106a51ffa4791a88ffd4765bf20c3"
 uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
-version = "0.6.0"
+version = "0.7.0"
 
 [[Documenter]]
-deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "LibGit2", "Logging", "Markdown", "Pkg", "REPL", "Random", "Test", "Unicode"]
-git-tree-sha1 = "de745be4b00336588ab3269d5f43517e5c012973"
+deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Unicode"]
+git-tree-sha1 = "c14469f5a9c4d6db4c9421de9c8a3858cea41bef"
+repo-rev = "fe/source-file"
+repo-url = "https://github.com/JuliaDocs/Documenter.jl.git"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.21.1"
+version = "0.22.1"
 
 [[FixedPointNumbers]]
 deps = ["Test"]
@@ -63,9 +65,9 @@ version = "0.5.3"
 
 [[GR]]
 deps = ["Base64", "DelimitedFiles", "LinearAlgebra", "Pkg", "Printf", "Random", "Serialization", "Sockets", "Test"]
-git-tree-sha1 = "3c62c19ddf86ff016829fdac1663cd3c75558c34"
+git-tree-sha1 = "08c4fc28ae58479f93616d5df164ab6b73541f2d"
 uuid = "28b8d3ca-fb5f-59d9-8090-bfdbd6d07a71"
-version = "0.37.0"
+version = "0.39.0"
 
 [[InteractiveUtils]]
 deps = ["LinearAlgebra", "Markdown"]
@@ -91,7 +93,7 @@ uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 deps = ["Base64", "JSON", "REPL"]
 path = ".."
 uuid = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-version = "1.0.2"
+version = "1.0.5"
 
 [[Logging]]
 uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
@@ -139,15 +141,15 @@ version = "0.3.0"
 
 [[PlotUtils]]
 deps = ["Colors", "Dates", "Printf", "Random", "Reexport", "Test"]
-git-tree-sha1 = "fd28f30a294a38ec847de95d8ac7ac916ccd7c06"
+git-tree-sha1 = "5da9a79a138db46558e6e08f649865b4c1f1ce93"
 uuid = "995b91a9-d308-5afd-9ec6-746e21dbc043"
-version = "0.5.5"
+version = "0.5.7"
 
 [[Plots]]
 deps = ["Base64", "Contour", "Dates", "FixedPointNumbers", "GR", "JSON", "LinearAlgebra", "Measures", "NaNMath", "Pkg", "PlotThemes", "PlotUtils", "Printf", "REPL", "Random", "RecipesBase", "Reexport", "Requires", "Showoff", "SparseArrays", "StaticArrays", "Statistics", "StatsBase", "Test", "UUIDs"]
-git-tree-sha1 = "1c345ad538fa31ea6953d89a9d0cbef21e86a3ed"
+git-tree-sha1 = "5bcc6dbc8b7fe0823d9a63dde87d7d4542149693"
 uuid = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
-version = "0.23.0"
+version = "0.24.0"
 
 [[Printf]]
 deps = ["Unicode"]
@@ -210,19 +212,19 @@ uuid = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [[StaticArrays]]
 deps = ["InteractiveUtils", "LinearAlgebra", "Random", "Statistics", "Test"]
-git-tree-sha1 = "1eb114d6e23a817cd3e99abc3226190876d7c898"
+git-tree-sha1 = "3841b39ed5f047db1162627bf5f80a9cd3e39ae2"
 uuid = "90137ffa-7385-5640-81b9-e52037218182"
-version = "0.10.2"
+version = "0.10.3"
 
 [[Statistics]]
 deps = ["LinearAlgebra", "SparseArrays"]
 uuid = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [[StatsBase]]
 deps = ["DataStructures", "DelimitedFiles", "LinearAlgebra", "Missings", "Printf", "Random", "SortingAlgorithms", "SparseArrays", "Statistics", "Test"]
-git-tree-sha1 = "7b596062316c7d846b67bf625d5963a832528598"
+git-tree-sha1 = "435707791dc85a67d98d671c1c3fcf1b20b00f94"
 uuid = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
-version = "0.27.0"
+version = "0.29.0"
 
 [[Test]]
 deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]

diff --git a/docs/make.jl b/docs/make.jl
@@ -33,6 +33,7 @@ end
 
 
 makedocs(
+    format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true"),
     modules = [Literate],
     sitename = "Literate.jl",
     pages = Any[

diff --git a/docs/src/fileformat.md b/docs/src/fileformat.md
@@ -108,3 +108,15 @@ The following convenience "macros" are always expanded:
   where `folder` is the folder that `Documenter.deploydocs` deploys too.
   This can be used if you want a link that opens the generated notebook in
   [http://nbviewer.jupyter.org/](http://nbviewer.jupyter.org/).
+
+- `@__BINDER_ROOT_URL__`
+
+  expands to
+  `https://mybinder.org/v2/gh/$(ENV["TRAVIS_REPO_SLUG"])/$(branch)?filepath=$(folder)/`
+  where `branch`/`folder` is the branch and folder where `Documenter.deploydocs`
+  deploys too. This can be used if you want a link that opens the generated notebook in
+  [https://mybinder.org/](https://mybinder.org/).
+  To add a binder-badge in e.g. the HTML output you can use:
+  ```
+  [![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__path/to/notebook.inpynb)
+  ```
diff --git a/examples/example.jl b/examples/example.jl
@@ -1,13 +1,19 @@
 # # **7.** Example
 #
+#md # [![](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__generated/example.inpynb)
+#md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__generated/example.ipynb)
+#
 # This is an example generated with Literate based on this
 # source file: [`example.jl`](@__REPO_ROOT_URL__examples/example.jl).
 # You are seeing the
-#md # html-output which Documenter have generated based on a markdown
+#md # HTML-output which Documenter have generated based on a markdown
 #md # file generated with Literate. The corresponding notebook
-#md # can be found here: [`example.ipynb`](@__NBVIEWER_ROOT_URL__generated/example.ipynb),
-#nb # generated notebook output. The corresponding markdown (html) output
-#nb # can be found here: [`example.html`](https://fredrikekre.github.io/Literate.jl/latest/generated/example.html),
+#md # can be viewed in [nbviewer](http://nbviewer.jupyter.org/) here:
+#md # [`example.ipynb`](@__NBVIEWER_ROOT_URL__generated/example.ipynb),
+#md # and opened in [binder](https://mybinder.org/) here:
+#md # [`example.ipynb`](@__BINDER_ROOT_URL__generated/example.ipynb),
+#nb # generated notebook output. The corresponding markdown (HTML) output
+#nb # can be found here: [`example.html`](https://fredrikekre.github.io/Literate.jl/dev/generated/example.html),
 # and the plain script output can be found here: [`example.jl`](./example.jl).
 
 # It is recommended to have the [source file](@__REPO_ROOT_URL__examples/example.jl)

diff --git a/src/Literate.jl b/src/Literate.jl
@@ -182,10 +182,14 @@ function replace_default(content, sym;
     repo_root_url = "https://github.com/$(travis_repo_slug)/blob/$(commit)/"
     push!(repls, "@__REPO_ROOT_URL__" => repo_root_url)
 
-    ## replace @__NBVIEWER_ROOT_URL__ to latest or version directory
+    ## replace @__NBVIEWER_ROOT_URL__ to dev or version directory
     nbviewer_root_url = "https://nbviewer.jupyter.org/github/$(travis_repo_slug)/blob/$(branch)/$(folder)/"
     push!(repls, "@__NBVIEWER_ROOT_URL__" => nbviewer_root_url)
 
+    ## replace $__BINDER_ROOT_URL__ to dev or version directory
+    binder_root_url = "https://mybinder.org/v2/gh/$(travis_repo_slug)/$(branch)?filepath=$(folder)/"
+    push!(repls, "@__BINDER_ROOT_URL__" => binder_root_url)
+
     if get(ENV, "HAS_JOSH_K_SEAL_OF_APPROVAL", "") != "true"
         @info "not running on Travis, skipping links will not be correct."
     end