From a759dc10bdffd8ffdfbe31b06c3627a5595b28f9 Mon Sep 17 00:00:00 2001
From: Shuhei Kadowaki <aviatesk@gmail.com>
Date: Fri, 27 Mar 2020 20:34:06 +0900
Subject: [PATCH 1/2] specify default output format (HMTL) for notebooks

---
 doc/src/usage.md | 21 +++++++++++++--------
 src/run.jl       | 22 +++++++++++++---------
 2 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/doc/src/usage.md b/doc/src/usage.md
index 8a5346b..355c7e6 100644
--- a/doc/src/usage.md
+++ b/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
diff --git a/src/run.jl b/src/run.jl
index 75b49f2..52bd7d8 100644
--- a/src/run.jl
+++ b/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
 
 

From d40e21ea35f0437234e1a69e52fcbe4853a07a79 Mon Sep 17 00:00:00 2001
From: Shuhei Kadowaki <aviatesk@gmail.com>
Date: Fri, 27 Mar 2020 20:43:33 +0900
Subject: [PATCH 2/2] improve documentations around notebooks

---
 doc/src/notebooks.md | 23 +++++++++++++----------
 src/Weave.jl         | 11 ++++++++++-
 2 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/doc/src/notebooks.md b/doc/src/notebooks.md
index 1351238..6c12855 100644
--- a/doc/src/notebooks.md
+++ b/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")
diff --git a/src/Weave.jl b/src/Weave.jl
index 7eda1b9..35eadec 100644
--- a/src/Weave.jl
+++ b/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;