Support configuration with a config::Dict kwarg. (#83)

fredrikekre · Nov 22, 2019 · 0f9e836 · 0f9e836
1 parent d3dc7c2
commit 0f9e836
Show file tree

Hide file tree

Showing 4 changed files with 143 additions and 120 deletions.
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
@@ -58,11 +58,9 @@ version = "0.8.1"
 
 [[Documenter]]
 deps = ["Base64", "Dates", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
-git-tree-sha1 = "fb16819c1bcf5e99b8e316e329e5e0958550334e"
-repo-rev = "master"
-repo-url = "https://github.com/JuliaDocs/Documenter.jl.git"
+git-tree-sha1 = "0e52069b5970cb27234153f578227947565152c5"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.24.0-DEV"
+version = "0.24.0"
 
 [[FFMPEG]]
 deps = ["BinaryProvider", "Libdl"]
@@ -116,7 +114,7 @@ uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 deps = ["Base64", "JSON", "REPL"]
 path = ".."
 uuid = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-version = "2.1.0"
+version = "2.1.1"
 
 [[Logging]]
 uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
@@ -153,12 +151,12 @@ version = "1.1.0"
 
 [[Parsers]]
 deps = ["Dates", "Test"]
-git-tree-sha1 = "a23968e107c0544aca91bfab6f7dd34de1206a54"
+git-tree-sha1 = "0139ba59ce9bc680e2925aec5b7db79065d60556"
 uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
-version = "0.3.9"
+version = "0.3.10"
 
 [[Pkg]]
-deps = ["Dates", "LibGit2", "Libdl", "Logging", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
+deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
 uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 
 [[PlotThemes]]

diff --git a/docs/make.jl b/docs/make.jl
@@ -20,24 +20,24 @@ 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)
-    str = replace(str, "[notebook.ipynb](generated/notebook.ipynb)." => "[notebook.ipynb]($(url)generated/notebook.ipynb).")
-    write(joinpath(@__DIR__, "src/outputformats.md"), str)
-end
+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)
+#     str = replace(str, "[notebook.ipynb](generated/notebook.ipynb)." => "[notebook.ipynb]($(url)generated/notebook.ipynb).")
+#     write(joinpath(@__DIR__, "src/outputformats.md"), str)
+# end
 
 
 makedocs(
     format = Documenter.HTML(
         assets = ["assets/custom.css"],
-
+        prettyurls = haskey(ENV, "GITHUB_ACTIONS"),
     ),
     modules = [Literate],
     sitename = "Literate.jl",

diff --git a/docs/src/outputformats.md b/docs/src/outputformats.md
@@ -12,7 +12,8 @@ and see how this is rendered in each of the output formats.
 
 ## [**4.1.** Markdown Output](@id Markdown-Output)
 
-The (default) markdown output of the source snippet above is as follows
+Markdown output is generated by [`Literate.markdown`](@ref). The (default) markdown output
+of the source snippet above is as follows:
 
 ```@eval
 import Markdown
@@ -28,24 +29,25 @@ 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):
+See the section about [Configuration](@ref) for how to configure the behavior and resulting
+output of [`Literate.markdown`](@ref).
 
 ```@docs
 Literate.markdown
 ```
 
 ## [**4.2.** Notebook Output](@id Notebook-Output)
 
-The (default) notebook output of the source snippet can be seen here:
-[notebook.ipynb](generated/notebook.ipynb).
+Notebook output is generated by [`Literate.notebook`](@ref). The (default) notebook output
+of the source snippet can be seen here: [notebook.ipynb](generated/notebook.ipynb).
 
 We note that lines starting with `# ` are placed in markdown cells,
 and the code lines have been placed in code cells. By default the notebook
 is also executed and output cells populated. The current working directory
 is set to the specified output directory the notebook is executed.
-Some of the output rendering can be controlled with keyword
-arguments to [`Literate.notebook`](@ref):
+
+See the section about [Configuration](@ref) for how to configure the behavior and resulting
+output of [`Literate.notebook`](@ref).
 
 ```@docs
 Literate.notebook
@@ -70,7 +72,8 @@ and the [reveal.js](https://github.com/hakimel/reveal.js) notebook extension
 
 ## [**4.3.** Script Output](@id Script-Output)
 
-The (default) script output of the source snippet above is as follows
+Script output is generated by [`Literate.script`](@ref). The (default) script output of the
+source snippet above is as follows:
 
 ```@eval
 import Markdown
@@ -81,9 +84,32 @@ Markdown.parse(str)
 ```
 
 We note that lines starting with `# ` are removed and only the
-code lines have been kept. Some of the output rendering can be controlled
-with keyword arguments to [`Literate.script`](@ref):
+code lines have been kept.
+
+See the section about [Configuration](@ref) for how to configure the behavior and resulting
+output of [`Literate.script`](@ref).
 
 ```@docs
 Literate.script
 ```
+
+## [**4.4.** Configuration](@id Configuration)
+
+The behavior of [`Literate.markdown`](@ref), [`Literate.notebook`](@ref) and
+[`Literate.script`](@ref) can be configured by keyword arguments. There are two
+ways to do this; pass `config::Dict` as a keyword argument, or pass individual
+keyword arguments.
+
+!!! note "Configuration precedence"
+    Individual keyword arguments takes precedence over the `config` dictionary, so for e.g.
+    `Literate.markdown(...; config = Dict("name" => "hello"), name = "world")` the
+    resulting configuration for `name` will be `"world"`. Both individual keyword arguments
+    and the `config` dictionary takes precedence over the default.
+
+Available configurations with description and default values are given in the reference for
+[`Literate.DEFAULT_CONFIGURATION`](@ref) just below.
+
+
+```@docs
+Literate.DEFAULT_CONFIGURATION
+```