easy doc access

README.md

@@ -40,25 +40,26 @@ using Pkg
 Pkg.add("Weave")
 ```
 
+
 ## Usage
 
-Run from julia using Plots.jl for plots:
-
 ```julia
-# First add depencies for the example
-using Pkg; Pkg.add.(["Plots", "DSP"])
-
-# Use Weave
 using Weave
-weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_path=:pwd)
+
+# add depencies for the example
+using Pkg; Pkg.add(["Plots", "DSP"])
+weave(Weave.SAMPLE_JMD_DOC, out_path = :pwd)
 ```
 
 If you have LaTeX installed you can also weave directly to pdf.
 
 ```julia
-weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_path = :pwd, doctype = "md2pdf")
+weave(Weave.SAMPLE_JMD_DOC), out_path = :pwd, doctype = "md2pdf")
 ```
 
+NOTE: `Weave.SAMPLE_JMD_DOC` is the path of [this document](./examples/FIR_design.jmd).
+
+
 ## Documentation
 
 Documenter.jl with MKDocs generated documentation:
@@ -66,6 +67,7 @@ Documenter.jl with MKDocs generated documentation:
 [![](https://img.shields.io/badge/docs-stable-blue.svg)](http://weavejl.mpastell.com/stable/)
 [![](https://img.shields.io/badge/docs-dev-blue.svg)](http://weavejl.mpastell.com/dev/)
 
+
 ## Editor support
 
 Install [language-weave](https://atom.io/packages/language-weave) to add Weave support to Juno.
@@ -75,16 +77,19 @@ html and pdf output.
 The [Julia extension for Visual Studio Code](https://www.julia-vscode.org/)
 adds Weave support to [Visual Studio Code](https://code.visualstudio.com/).
 
+
 ## Contributing
 
 You can contribute to this package by opening issues on GitHub or implementing things yourself and making a pull request.
 We'd also appreciate more example documents written using Weave.
 
+
 ## Contributors
 
 You can see the list of contributors on GitHub: https://github.com/JunoLab/Weave.jl/graphs/contributors .
 Thanks for the important additions, fixes and comments.
 
+
 ## Example projects using Weave
 
 - [DiffEqTutorials.jl](https://github.com/JuliaDiffEq/DiffEqTutorials.jl) uses Weave to output tutorials (`.jmd` documents) to html, pdf and Jupyter notebooks.

doc/src/getting_started.md

@@ -5,10 +5,8 @@ The best way to get started using Weave.jl is to look at the example input and
 output documents. Examples for different formats are included in the packages
 [`examples`](https://github.com/JunoLab/Weave.jl/tree/master/examples) directory.
 
-First have a look at source document using markdown code chunks and
-[Plots.jl](https://github.com/JuliaPlots/Plots.jl) for figures:
-[FIR_design.jmd](../examples/FIR_design.jmd) and then see the
-output in different formats:
+First have a look at source document using markdown code chunks and [Plots.jl](https://github.com/JuliaPlots/Plots.jl) for figures:
+[FIR_design.jmd](../examples/FIR_design.jmd) (its path is bound to `Weave.SAMPLE_JMD_DOC`) and then see the output in different formats:
 
 - HTML: [`FIR_design.html`](../examples/FIR_design.html)
 - PDF: [`FIR_design.pdf`](../examples/FIR_design.pdf)
@@ -29,23 +27,14 @@ Weave the files to your working directory:
 using Weave
 
 # Julia markdown to HTML
-weave(
-  joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd");
-  doctype = "md2html",
-  out_path = :pwd
-)
+weave(Weave.SAMPLE_JMD_DOC; doctype = "md2html", out_path = :pwd)
 
 # Julia markdown to PDF
-weave(
-  joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd");
-  doctype = "md2pdf",
-  out_path = :pwd
-)
+weave(Weave.SAMPLE_JMD_DOC; doctype = "md2pdf", out_path = :pwd)
 
 # Julia markdown to Pandoc markdown
-weave(
-  joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd");
-  doctype = "pandoc",
-  out_path = :pwd
-)
+weave(Weave.SAMPLE_JMD_DOC; doctype = "pandoc", out_path = :pwd)
 ```
+
+!!! tips
+    `Weave.SAMPLE_JMD_DOC` is the path of [FIR_design.jmd](../examples/FIR_design.jmd).

doc/src/publish.md

@@ -16,16 +16,19 @@ date: 15th December 2016
 ```
 
 Here are sample input and outputs:
-- input (Julia markdown format): [`FIR_design_plots.jl`](../examples/FIR_design_plots.jl)
+- input (Julia markdown format): [`FIR_design_plots.jl`](../examples/FIR_design_plots.jl) (its path is bound to `Weave.SAMPLE_JL_DOC`)
 - HTML output: [`FIR_design_plots.html`](../examples/FIR_design_plots.html)
 -  PDF output: [`FIR_design_plots.pdf`](../examples/FIR_design_plots.pdf)
 
 They are generated as follows:
 ```julia
-weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design_plots.jl")) # default to md2html output format
-weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design_plots.jl"), doctype = "md2pdf")
+weave(Weave.SAMPLE_JL_DOC)) # default to md2html output format
+weave(Weave.SAMPLE_JL_DOC; doctype = "md2pdf")
 ```
 
+!!! tips
+    `Weave.SAMPLE_JL_DOC` is the path of [FIR_design.jl](../examples/FIR_design.jl).
+
 !!! note
     `"md2html"` and `"md2pdf"` assume Julia markdown format as an input,
     while `pandoc2pdf` and `pandoc2html` assume Noweb input format (i.e. Pandoc markdown).

doc/src/usage.md

@@ -8,13 +8,13 @@ syntax and use [`weave`](@ref) function to execute to document to capture result
 Weave document with markup and julia code using `Plots.jl` for plots,
 `out_path = :pwd` makes the results appear in the current working directory.
 
-> A prepared example
+> A prepared example: [`Weave.SAMPLE_JL_DOC`](../examples/FIR_design.jmd)
 
 ```julia
 # First add depencies for the example
 using Pkg; Pkg.add.(["Plots", "DSP"])
 using Weave
-weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_path=:pwd)
+weave(Weave.SAMPLE_JL_DOC; out_path=:pwd)
 ```
 
 ```@docs

examples/FIR_design.jmd

@@ -22,6 +22,13 @@ If you're viewing the published version have a look at the
 [source](FIR_design_plots.jl) to see the markup.
 
 
+<!-- this setup dependencies, but doesn't appear in the generated document -->
+```julia; echo = false; results = "hidden"
+using Pkg
+"Plots" ∉ keys(Pkg.project().dependencies) && Pkg.add("Plots")
+"DSP" ∉ keys(Pkg.project().dependencies) && Pkg.add("DSP")
+```
+
 
 # FIR Filter Design
 

src/Weave.jl

@@ -8,6 +8,11 @@ const TEMPLATE_DIR = normpath(PKG_DIR, "templates")
 const WEAVE_OPTION_NAME = "weave_options"
 const WEAVE_OPTION_NAME_DEPRECATED = "options" # remove this when tagging v0.11
 
+# keeps paths of sample documents for easy try
+const SAMPLE_JMD_DOC = normpath(PKG_DIR, "examples", "FIR_design.jmd")
+const  SAMPLE_JL_DOC = normpath(PKG_DIR, "examples", "FIR_design.jl")
+
+
 function __init__()
     @require Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" include("plots.jl")
     @require Gadfly = "c91e804a-d5a3-530f-b6f0-dfbca275c004" include("gadfly.jl")