more docs for interaction with Documenter

README.md

@@ -1,9 +1,13 @@
 # Examples
 
-| **Documentation**                                                               | **Build Status**                                                                                |
+| **Documentation**                       | **Build Status**                                                                                |
-|:------------------------------------------------------------------------------- |:-----------------------------------------------------------------------------------------------|
+|:--------------------------------------- |:----------------------------------------------------------------------------------------------- |
-| [![][docs-stable-img]][docs-stable-url] [![][docs-latest-img]][docs-latest-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] |
+| [![][docs-latest-img]][docs-latest-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] |
-
+
+`Examples.jl` is a package that, based on a single source file, generates markdown,
+for e.g. [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl),
+[Jupyter notebooks](http://jupyter.org/) and uncommented scripts for documentation
+of your package.
 
 
 [docs-latest-img]: https://img.shields.io/badge/docs-latest-blue.svg

docs/make.jl

@@ -5,9 +5,9 @@ using Examples
 EXAMPLE = joinpath(@__DIR__, "..", "examples", "example.jl")
 OUTPUT = joinpath(@__DIR__, "src/generated")
 
-Examples.markdown(EXAMPLE, OUTPUT)
+Examples.markdown(EXAMPLE, OUTPUT; documenter = true)
-Examples.notebook(EXAMPLE, OUTPUT)
+Examples.notebook(EXAMPLE, OUTPUT; documenter = true)
-Examples.script(EXAMPLE, OUTPUT)
+Examples.script(EXAMPLE, OUTPUT; documenter = true)
 
 makedocs(
     modules = [Examples],

docs/src/documenter.md

@@ -1,3 +1,36 @@
 # [**6.** Interaction with Documenter.jl](@id Interaction-with-Documenter)
 
-TBW
+`Examples.jl` can be used for any purpose, it spits out regular markdown files,
+and notebooks. Typically, though, these files will be used to render documentation
+for your package. The generators ([`Examples.markdown`](@ref), [`Examples.notebook`](@ref)
+and [`Examples.script`](@ref)) supports a keyword argument `documenter` that lets
+the generator perform some extra things, keeping in mind that the generated files will,
+eventually, be used with Documenter.jl. So lets take a look at what will happen
+if we set `documenter = true`:
+
+[`Examples.markdown`](@ref):
+- The default code fence will change from
+  ````
+  ```julia
+  # code
+  ```
+  ````
+  to Documenters `@example` blocks:
+  ````
+  ```@examples $(name)
+  # code
+  ```
+  ````
+- The following `@meta` block will be added to the top of the markdown page,
+  which redirects the "Edit on GitHub" link on the top of the page to the
+  *source file* rather than the generated `.md` file:
+  ````
+  ```@meta
+  EditURL = "$(relpath(inputfile, outputdir))"
+  ```
+  ````
+
+[`Examples.notebook`](@ref):
+- Documenter style `@ref`s and `@id` will be removed. This means that you can use
+  `@ref` and `@id` in the source file without them leaking to the notebook.
+

src/Examples.jl

@@ -170,16 +170,22 @@ Keyword arguments:
   see the [Custom pre- and post-processing](@ref Custom-pre-and-post-processing)
   section of the manual. Defaults to `identity`.
 - `codefence`: A `Pair` of opening and closing code fence. Defaults to
+  ````
+  "```julia" => "```"
+  ````
+  if `documenter = false` and
   ````
   "```@example \$(name)" => "```"
   ````
+  if `documenter = true`.
 - `documenter`: boolean that says if the output is intended to use with Documenter.jl.
   Defaults to `false`. See the the manual section on
   [Interaction with Documenter](@ref Interaction-with-Documenter).
 """
 function markdown(inputfile, outputdir; preprocess = identity, postprocess = identity,
                   name = filename(inputfile), documenter::Bool = false,
-                  codefence::Pair = "```@example $(name)" => "```", kwargs...)
+                  codefence::Pair = documenter ? "```@example $(name)" => "```" : "```julia" => "```",
+                  kwargs...)
     # normalize paths
     inputfile = realpath(abspath(inputfile))
     mkpath(outputdir)
@@ -208,6 +214,17 @@ function markdown(inputfile, outputdir; preprocess = identity, postprocess = ide
         content = replace(content, repl)
     end
 
+    # run some Documenter specific things
+    if documenter
+        # change the Edit on GitHub link
+        content = """
+        #' ```@meta
+        #' EditURL = "$(relpath(inputfile, outputdir))"
+        #' ```
+
+        """ * content
+    end
+
     # create the markdown file
     chunks = parse(content)
     iomd = IOBuffer()
@@ -220,7 +237,7 @@ function markdown(inputfile, outputdir; preprocess = identity, postprocess = ide
         else # isa(chunk, CodeChunk)
             write(iomd, codefence.first)
             # make sure the code block is finalized if we are printing to ```@example
-            if chunk.continued && startswith(codefence.first, "```@example")
+            if chunk.continued && startswith(codefence.first, "```@example") && documenter
                 write(iomd, "; continued = true")
             end
             write(iomd, '\n')
@@ -297,6 +314,21 @@ function notebook(inputfile, outputdir; preprocess = identity, postprocess = ide
         content = replace(content, repl)
     end
 
+    # run some Documenter specific things
+    if documenter # TODO: safe to do this always?
+        # remove documenter style `@ref`s and `@id`s
+        # TODO: remove @docs, @setup etc? Probably not, since these are complete blocks
+        #       and the user can just mark those lines with #md
+        for repl in Pair{Any,Any}[
+                    r"\[(.*?)\]\(@ref\)" => s"\1",
+                    r"\[(.*?)\]\(@ref .*?\)" => s"\1",
+                    r"\[(.*?)\]\(@id .*?\)" => s"\1",
+                ]
+            content = replace(content, repl)
+        end
+    end
+
+
     # custom post-processing from user
     content = postprocess(content)