internal API improvements

bin/weave.jl

@@ -14,14 +14,14 @@ ap = ArgParseSettings("Weave Julia documents using Weave.jl",
         help = "source document(s)"
         required = true
     "--doctype"
-        default = :auto
+        default = nothing
         help = "output format"
     "--plotlib"
         arg_type = String
         default = "Gadfly"
         help = "output format"
     "--informat"
-        default = :auto
+        default = nothing
         help = "output format"
     "--out_path"
         arg_type = String
@@ -43,9 +43,6 @@ args_col = []
 
 #Check for special values of out_path
 
-#args["informat"] == ":auto" && (args["informat"] = :auto)
-#args["doctype"] == ":auto" && (args["informat"] = :auto)
-
 if args["out_path"] == ":doc"
     args["out_path"] = :doc
 elseif args["out_path"] == ":pwd"

src/Weave.jl

@@ -39,7 +39,7 @@ Tangle source code from input document to .jl file.
 
 ## Keyword options
 
-- `informat::Union{Symbol,AbstractString} = :auto`: Input document format. `:auto` will set it automatically based on file extension. You can also specify either of `"script"`, `"markdown"`, `"notebook"`, or `"noweb"`
+- `informat::Union{Nothing,AbstractString} = nothing`: Input document format. By default (i.e. given `nothing`), Weave will set it automatically based on file extension. You can also specify either of `"script"`, `"markdown"`, `"notebook"`, or `"noweb"`
 - `out_path::Union{Symbol,AbstractString} = :doc`: Path where the output is generated can be either of:
   * `:doc`: Path of the source document (default)
   * `:pwd`: Julia working directory
@@ -48,9 +48,9 @@ Tangle source code from input document to .jl file.
 function tangle(
     source::AbstractString;
     out_path::Union{Symbol,AbstractString} = :doc,
-    informat::Union{Symbol,AbstractString} = :auto,
+    informat::Union{Nothing,AbstractString} = nothing,
 )
-    doc = read_doc(source, informat)
+    doc = WeaveDoc(source, informat)
     doc.cwd = get_cwd(doc, out_path)
 
     outname = get_outname(out_path, doc, ext = "jl")
@@ -74,8 +74,8 @@ Weave an input document to output file.
 
 ## Keyword options
 
-- `doctype::Union{Symbol,AbstractString} = :auto`: Output document format. `:auto` will set it automatically based on file extension. You can also manually specify it; see [`list_out_formats()`](@ref) for the supported formats
-- `informat::Union{Symbol,AbstractString} = :auto`: Input document format. `:auto` will set it automatically based on file extension. You can also specify either of `"script"`, `"markdown"`, `"notebook"`, or `"noweb"`
+- `doctype::Union{Nothing,AbstractString} = nothing`: Output document format. By default (i.e. given `nothing`), Weave will set it automatically based on file extension. You can also manually specify it; see [`list_out_formats()`](@ref) for the supported formats
+- `informat::Union{Nothing,AbstractString} = nothing`: Input document format. By default (i.e. given `nothing`), Weave will set it automatically based on file extension. You can also specify either of `"script"`, `"markdown"`, `"notebook"`, or `"noweb"`
 - `out_path::Union{Symbol,AbstractString} = :doc`: Path where the output is generated can be either of:
   * `:doc`: Path of the source document (default)
   * `:pwd`: Julia working directory
@@ -103,8 +103,8 @@ Weave an input document to output file.
 """
 function weave(
     source::AbstractString;
-    doctype::Union{Symbol,AbstractString} = :auto,
-    informat::Union{Symbol,AbstractString} = :auto,
+    doctype::Union{Nothing,AbstractString} = nothing,
+    informat::Union{Nothing,AbstractString} = nothing,
     out_path::Union{Symbol,AbstractString} = :doc,
     args::Dict = Dict(),
     mod::Union{Module,Nothing} = nothing,
@@ -120,8 +120,8 @@ function weave(
     latex_cmd::AbstractString = "xelatex",
     latex_keep_unicode::Bool = false,
 )
-    doc = read_doc(source, informat)
-    doctype == :auto && (doctype = detect_doctype(doc.source))
+    doc = WeaveDoc(source, informat)
+    isnothing(doctype) && (doctype = detect_doctype(doc.source))
     doc.doctype = doctype
 
     # Read args from document header, overrides command line args
@@ -240,7 +240,7 @@ function notebook(
     nbconvert_options::AbstractString = "",
     jupyter_path::AbstractString = "jupyter",
 )
-    doc = read_doc(source)
+    doc = WeaveDoc(source)
     converted = convert_doc(doc, NotebookOutput())
     doc.cwd = get_cwd(doc, out_path)
     outfile = get_outname(out_path, doc, ext = "ipynb")
@@ -257,19 +257,19 @@ function notebook(
 end
 
 """
-    include_weave(source::AbstractString, informat::Union{Symbol,AbstractString} = :auto)
-    include_weave(m::Module, source::AbstractString, informat::Union{Symbol,AbstractString} = :auto)
+    include_weave(source::AbstractString, informat::Union{Nothing,AbstractString} = nothing)
+    include_weave(m::Module, source::AbstractString, informat::Union{Nothing,AbstractString} = nothing)
 
 Include code from Weave document calling `include_string` on all code from doc.
 Code is run in the path of the include document.
 """
 function include_weave(
     m::Module,
     source::AbstractString,
-    informat::Union{Symbol,AbstractString} = :auto,
+    informat::Union{Nothing,AbstractString} = nothing,
 )
     old_path = pwd()
-    doc = read_doc(source, informat)
+    doc = WeaveDoc(source, informat)
     cd(doc.path)
     try
         code = join(
@@ -284,7 +284,7 @@ function include_weave(
     end
 end
 
-include_weave(source, informat = :auto) = include_weave(Main, source, informat)
+include_weave(source, informat = nothing) = include_weave(Main, source, informat)
 
 # Hooks to run before and after chunks, this is form IJulia,
 # but note that Weave hooks take the chunk as input

src/config.jl

@@ -108,7 +108,7 @@ function header_args(
     args = get(doc.header, WEAVE_OPTION_NAME, Dict())
     doctype = get(args, "doctype", doc.doctype)
     args = combine_args(args, doctype)
-    informat = get(args, "informat", :auto)
+    informat = get(args, "informat", nothing)
     out_path = get(args, "out_path", out_path)
     out_path == ":pwd" && (out_path = :pwd)
     isa(out_path, Symbol) || (out_path = joinpath(dirname(doc.source), out_path))

src/format.jl

@@ -140,7 +140,7 @@ function strip_header!(docchunk::DocChunk, doctype)
         end
     end
 end
-strip_header!(codechunk::CodeChunk, doctype) = nothing
+strip_header!(codechunk::CodeChunk, doctype) = return
 
 function format_chunk(chunk::DocChunk, formatdict, docformat)
     return join([format_inline(c) for c in chunk.content], "")

src/reader/reader.jl

@@ -1,19 +1,14 @@
 using JSON, YAML
 
 
-"""
-    read_doc(source, format = :auto)
-
-Read the input document from `source` and parse it into [`WeaveDoc`](@ref).
-"""
-function read_doc(source, format = :auto)
-    document = replace(read(source, String), "\r\n" => "\n") # fix line ending
-    format === :auto && (format = detect_informat(source))
+function WeaveDoc(source, format::Union{Nothing,AbstractString} = nothing)
+    document = replace(read(source, String), "\r\n" => "\n") # normalize line ending
+    isnothing(format) && (format = detect_informat(source))
     chunks = parse_doc(document, format)
     return WeaveDoc(source, chunks)
 end
 
-function WeaveDoc(source, chunks)
+function WeaveDoc(source, chunks::Vector{WeaveChunk})
     path, fname = splitdir(abspath(source))
     basename = splitext(fname)[1]
 

src/run.jl

@@ -7,7 +7,7 @@ Run code chunks and capture output from the parsed document.
 
 ## Keyword options
 
-- `doctype::Union{Symbol,AbstractString} = :auto`: Output document format. `:auto` will set it automatically based on file extension. You can also manually specify it; see [`list_out_formats()`](@ref) for the supported formats
+- `doctype::Union{Nothing,AbstractString} = nothing`: Output document format. By default (i.e. given `nothing`), Weave will set it automatically based on file extension. You can also manually specify it; see [`list_out_formats()`](@ref) for the supported formats
 - `out_path::Union{Symbol,AbstractString} = :doc`: Path where the output is generated can be either of:
   * `:doc`: Path of the source document (default)
   * `:pwd`: Julia working directory
@@ -30,7 +30,7 @@ Run code chunks and capture output from the parsed document.
 """
 function run_doc(
     doc::WeaveDoc;
-    doctype::Union{Symbol,AbstractString} = :auto,
+    doctype::Union{Nothing,AbstractString} = nothing,
     out_path::Union{Symbol,AbstractString} = :doc,
     args::Dict = Dict(),
     mod::Union{Module,Nothing} = nothing,
@@ -45,7 +45,7 @@ function run_doc(
 
     doc.cwd = get_cwd(doc, out_path)
     # doctype detection is unnecessary here, but existing unit test requires this.
-    doctype === :auto && (doctype = detect_doctype(doc.source))
+    isnothing(doctype) && (doctype = detect_doctype(doc.source))
     doc.doctype = doctype
     doc.format = formats[doctype]
 
@@ -123,12 +123,12 @@ function run_doc(
 end
 
 """
-    detect_doctype(path::AbstractString)
+    detect_doctype(pathname::AbstractString)
 
 Detect the output format based on file extension.
 """
-function detect_doctype(path::AbstractString)
-    _, ext = lowercase.(splitext(path))
+function detect_doctype(pathname::AbstractString)
+    _, ext = lowercase.(splitext(pathname))
 
     match(r"^\.(jl|.?md|ipynb)", ext) !== nothing && return "md2html"
     ext == ".rst" && return "rst"

src/writers.jl

@@ -40,19 +40,15 @@ function convert_doc(
     outfile::AbstractString;
     format::Union{Nothing,AbstractString} = nothing,
 )
-    doc = read_doc(infile)
+    doc = WeaveDoc(infile)
 
-    if format == nothing
-        format = detect_outformat(outfile)
-    end
+    isnothing(format) && (format = detect_outformat(outfile))
 
     converted = convert_doc(doc, output_formats[format])
 
     open(outfile, "w") do f
         write(f, converted)
     end
-
-    return nothing
 end
 
 """Convert Weave document to Jupyter notebook format"""

test/convert_test.jl

@@ -15,7 +15,7 @@ convert_test("chunk_options.jl")
 convert_test("chunk_options.mdw")
 convert_test("chunk_options_nb.mdw", "documents/chunk_options.ipynb")
 
-# Separate test for notebook (output depends on julia version)  
+# Separate test for notebook (output depends on julia version)
 function contents(chunk::Weave.DocChunk)
   return join([strip(c.content) for c in chunk.content], "")
 end
@@ -31,12 +31,10 @@ end
 outfile = "documents/convert/chunk_options.ipynb"
 infile = "documents/chunk_options.noweb"
 convert_doc(infile, outfile)
-input = contents(Weave.read_doc(infile))  
-output = contents(Weave.read_doc(outfile))
+input = contents(Weave.WeaveDoc(infile))
+output = contents(Weave.WeaveDoc(outfile))
 @test input == output
 rm(outfile)
 
 # Test script reader
-@test contents(
-    Weave.read_doc("documents/chunk_options.noweb")) == contents(
-      Weave.read_doc("documents/chunk_options.jl"))
+@test contents(Weave.WeaveDoc("documents/chunk_options.noweb")) == contents(Weave.WeaveDoc("documents/chunk_options.jl"))

test/formatter_test.jl

@@ -18,7 +18,7 @@ f = Weave.format_chunk(dchunk, docformat.formatdict, docformat)
 
 # Test with actual doc
 
-parsed = Weave.read_doc("documents/chunk_options.noweb")
+parsed = Weave.WeaveDoc("documents/chunk_options.noweb")
 doc = run_doc(parsed, doctype = "md2html")
 
 c_check = "<pre class='hljl'>\n<span class='hljl-n'>x</span><span class='hljl-t'> </span><span class='hljl-oB'>=</span><span class='hljl-t'> </span><span class='hljl-p'>[</span><span class='hljl-ni'>12</span><span class='hljl-p'>,</span><span class='hljl-t'> </span><span class='hljl-ni'>10</span><span class='hljl-p'>]</span><span class='hljl-t'>\n</span><span class='hljl-nf'>println</span><span class='hljl-p'>(</span><span class='hljl-n'>y</span><span class='hljl-p'>)</span>\n</pre>\n"
@@ -35,7 +35,7 @@ rendered = Weave.render_doc("Hello", doc, doc.format)
 @test rendered == "\nHello\n"
 
 # Tex format
-parsed = Weave.read_doc("documents/chunk_options.noweb")
+parsed = Weave.WeaveDoc("documents/chunk_options.noweb")
 doc = run_doc(parsed, doctype = "md2tex")
 
 c_check = "\\begin{lstlisting}\n(*@\\HLJLnf{println}@*)(*@\\HLJLp{(}@*)(*@\\HLJLn{x}@*)(*@\\HLJLp{)}@*)\n\\end{lstlisting}\n"
@@ -97,7 +97,7 @@ tfied = "\\ensuremath{\\bm{\\mathrm{L}}} \\ensuremath{\\bm{\\mathfrak{F}}} \\ens
 @test Weave.uc2tex("𝐋 𝕱 𝛊 𝔄 𝚹") == tfied
 
 # Test markdown output from chunks
-parsed = Weave.read_doc("documents/markdown_output.jmd")
+parsed = Weave.WeaveDoc("documents/markdown_output.jmd")
 doc = run_doc(parsed, doctype = "md2html")
 @test doc.chunks[1].rich_output == "\n<div class=\"markdown\"><h3>Small markdown sample</h3>\n<p><strong>Hello</strong> from <code>code</code> block.</p>\n</div>"
 @test doc.chunks[2].rich_output == "\n<div class=\"markdown\"><ul>\n<li><p>one</p>\n</li>\n<li><p>two</p>\n</li>\n<li><p>three</p>\n</li>\n</ul>\n</div>"