Merge pull request #296 from JunoLab/avi/notebook

Specify HTML as a default output format for weaving notebooks

doc/src/notebooks.md

@@ -3,27 +3,30 @@
 
 ## Weaving from Jupyter notebooks
 
-Weave supports using Jupyter notebooks as input format, this means you
-can weave notebooks to any supported formats. You can't use chunk options with notebooks.
+Weave supports using [Jupyter Notebook](https://jupyter.org/)s as input format.
+This means you can [`weave`](@ref) notebooks to any supported formats;
+by default, it will be weaved to HTML.
 
 ```julia
-weave("notebook.ipynb")
+weave("notebook.ipynb") # will be weaved to HTML
 ```
 
+!!! warning
+    You can't use chunk options with notebooks.
+
 ## Output to Jupyter notebooks
 
-As of Weave 0.5.1. there is new `notebook` method to convert Weave documents
-to Jupyter notebooks using [nbconvert](http://nbconvert.readthedocs.io/en/latest/execute_api.html). The code **is not executed by Weave**
-and the output doesn't always work properly,
-see [#116](https://github.com/mpastell/Weave.jl/issues/116).
+As of Weave 0.5.1. there is new [`notebook`](@ref) method to convert Weave documents to Jupyter notebooks using
+[nbconvert](http://nbconvert.readthedocs.io/en/latest/execute_api.html).
 
 ```@docs
 notebook
 ```
 
-You might want to use the [`convert_doc`](@ref) method below instead and run the code in Jupyter.
+You can specify `jupyter` used to execute the notebook with the `jupyter_path` keyword argument
+(this defaults to the `"jupyter"`, i.e. whatever you have linked to that location).
 
-You can select the `jupyter` used to execute the notebook with the `jupyter_path` argument (this defaults to the string "jupyter," i.e., whatever you have linked to that location.)
+Instead, you might want to use the [`convert_doc`](@ref) method below and run the code in Jupyter.
 
 ## Converting between formats
 
@@ -35,7 +38,7 @@ To convert from script to notebook:
 convert_doc("examples/FIR_design.jl", "FIR_design.ipynb")
 ```
 
-and from notebooks to markdown use:
+and from notebook to Markdown use:
 
 ```julia
 convert_doc("FIR_design.ipynb", "FIR_design.jmd")

doc/src/usage.md

@@ -31,18 +31,23 @@ tangle
 
 ## Supported output formats
 
-Weave sets the output format based on the file extension, but you can also set
-it using `doctype` option. The rules for detecting the format are:
+Weave automatically detects the output format based on the file extension.
+The auto output format detection is handled by `detect_doctype(path::AbstractString)`:
 
 ```julia
-ext == ".jl" && return "md2html"
-contains(ext, ".md") && return "md2html"
-contains(ext, ".rst") && return "rst"
-contains(ext, ".tex") && return "texminted"
-contains(ext, ".txt") && return "asciidoc"
-return "pandoc"
+function detect_doctype(path::AbstractString)
+    _, ext = lowercase.(splitext(path))
+
+    match(r"^\.(jl|.?md|ipynb)", ext) !== nothing && return "md2html"
+    ext == ".rst" && return "rst"
+    ext == ".tex" && return "texminted"
+    ext == ".txt"  && return "asciidoc"
+
+    return "pandoc"
+end
 ```
 
+You can also manually specify it using the `doctype` keyword option.
 You can get a list of supported output formats:
 
 ```@docs

src/Weave.jl

@@ -182,7 +182,8 @@ weave(doc::AbstractString, doctype::Union{Symbol,AbstractString}) =
 """
     notebook(source::AbstractString; kwargs...)
 
-Convert Weave document `source` to Jupyter notebook and execute the code using `nbconvert`.
+Convert Weave document `source` to Jupyter Notebook and execute the code
+using [`nbconvert`](https://nbconvert.readthedocs.io/en/latest/).
 **Ignores** all chunk options.
 
 ## Keyword options
@@ -194,6 +195,14 @@ Convert Weave document `source` to Jupyter notebook and execute the code using `
 - `timeout = -1`: nbconvert cell timeout in seconds. Defaults to `-1` (no timeout)
 - `nbconvert_options::AbstractString = ""`: `String` of additional options to pass to nbconvert, such as `"--allow-errors"`
 - `jupyter_path::AbstractString = "jupyter"`: Path/command for the Jupyter you want to use. Defaults to `"jupyter"`, which runs whatever is linked/alias to that
+
+!!! warning
+    The code is _**not**_ executed by Weave, but by [`nbconvert`](https://nbconvert.readthedocs.io/en/latest/).
+    This means that the output doesn't necessarily always work properly; see [#116](https://github.com/mpastell/Weave.jl/issues/116).
+
+!!! note
+    In order to _just_ convert Weave document to Jupyter Notebook,
+    use [`convert_doc`](@ref) instead.
 """
 function notebook(
     source::AbstractString;

src/run.jl

@@ -131,16 +131,20 @@ function Base.run(
     return doc
 end
 
-"""Detect the output format based on file extension"""
-function detect_doctype(source::AbstractString)
-  ext = lowercase(splitext(source)[2])
-  ext == ".jl" && return "md2html"
-  occursin("md", ext) && return "md2html"
-  occursin("rst", ext) && return "rst"
-  occursin("tex", ext) && return "texminted"
-  occursin("txt", ext) && return "asciidoc"
+"""
+    detect_doctype(path::AbstractString)
 
-  return "pandoc"
+Detect the output format based on file extension.
+"""
+function detect_doctype(path::AbstractString)
+    _, ext = lowercase.(splitext(path))
+
+    match(r"^\.(jl|.?md|ipynb)", ext) !== nothing && return "md2html"
+    ext == ".rst" && return "rst"
+    ext == ".tex" && return "texminted"
+    ext == ".txt"  && return "asciidoc"
+
+    return "pandoc"
 end