diff --git a/.gitignore b/.gitignore index e3a75cc..60bcbe0 100644 --- a/.gitignore +++ b/.gitignore @@ -19,7 +19,9 @@ test/documents/*.pdf test/documents/chunk_options.jl !test/documents/*ref.* - +doc/build +doc/site +stable/ tmp/ .idea diff --git a/README.md b/README.md index 714a913..e48aac4 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,9 @@ weave(Pkg.dir("Weave","examples","gadfly_sample.mdw")) ## Documentation -Lexicon.jl generated documentation for [v0.0.4](http://mpastell.github.io/Weave.jl/v0.0.4/) and [master](http://mpastell.github.io/Weave.jl/master/). +Documenter.jl with MKdDocs generated documentation: + +[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://mpastell.github.io/Weave.jl/stable) ## Contributing diff --git a/REQUIRE b/REQUIRE index dd93ddd..c432c42 100644 --- a/REQUIRE +++ b/REQUIRE @@ -1,5 +1,4 @@ julia 0.4 Compat ArgParse -Docile JSON diff --git a/doc/make.jl b/doc/make.jl new file mode 100644 index 0000000..c6eba83 --- /dev/null +++ b/doc/make.jl @@ -0,0 +1,3 @@ +using Documenter, Weave + +makedocs(modules = Weave) diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml new file mode 100644 index 0000000..758a5e7 --- /dev/null +++ b/doc/mkdocs.yml @@ -0,0 +1,29 @@ +site_name: Weave.jl - Scientific Reports Using Julia +site_author: Matti Pastell +copyright: Matti Pastell 2016 +repo_url: https://github.com/mpastell/Weave.jl + +theme: material + +extra: + palette: + primary: 'indigo' + accent: 'blue' + +extra_css: + - assets/Documenter.css + +extra_javascript: + - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML + - assets/mathjaxhelper.js + +markdown_extensions: + - extra + - tables + - fenced_code + - mdx_math + +docs_dir: 'build' + +pages: + - Home: index.md diff --git a/doc/manual.md b/doc/src/index.md similarity index 93% rename from doc/manual.md rename to doc/src/index.md index 010abe9..ec45b68 100644 --- a/doc/manual.md +++ b/doc/src/index.md @@ -1,4 +1,6 @@ +# Intro + This is the documentation of [Weave.jl](http://github.com/mpastell/weave.jl). Weave is a scientific report generator/literate programming tool for Julia. It resembles [Pweave](http://mpastell.com/pweave) and, Knitr and Sweave. @@ -9,9 +11,13 @@ You can write your documentation and code in input document using Nowed or Markd * Noweb or markdown syntax for input documents. * Execute code as terminal or "script" chunks. -* Capture PyPlot, Gadfly or Winston figures. +* Capture PyPlot or Gadfly figures. * Supports LaTex, Pandoc and Github markdown and reStructuredText output + {contents} + + + # Document syntax Weave uses noweb or markdown syntax for defining the code chunks and documentation chunks. @@ -76,6 +82,8 @@ Weave currently supports the following chunk options with the following defaults # Usage +## Weave + Run from julia using Gadfly for plots: ```julia @@ -83,28 +91,38 @@ using Weave weave(Pkg.dir("Weave","examples","gadfly_sample.mdw")) ``` -Using Winston for plots (Julia 0.3 and Weave.jl 0.04 only): - -```julia -weave(Pkg.dir("Weave","examples","winston_sample.mdw"), -plotlib="Winston", doctype="pandoc") -``` - Using PyPlot: ```julia weave(Pkg.dir("Weave","examples","julia_sample.mdw"), plotlib="PyPlot") ``` -## File formats + {docs} + weave(source) + +## Tangle + +Tangling extracts the code from document: + + {docs} + tangle(source) + + + +## Supported formats You can get a list of supported output formats: -```julia +``` julia> list_out_formats() pandoc: Pandoc markdown rst: reStructuredText and Sphinx texminted: Latex using minted for highlighting github: Github markdown +asciidoc: AsciiDoc tex: Latex with custom code environments ``` + +# Index + + {index} diff --git a/src/Weave.jl b/src/Weave.jl index ed7945c..eb77f28 100644 --- a/src/Weave.jl +++ b/src/Weave.jl @@ -1,8 +1,5 @@ module Weave using Compat -using Docile - -@docstrings(manual = ["../doc/manual.md"]) #Contains report global properties type Report <: Display @@ -37,7 +34,11 @@ function Base.display(doc::Report, data) end end -@doc "List supported output formats" -> +""" +list_out_formats() + +List supported output formats +""" function list_out_formats() for format = keys(formats) println(string(format,": ", formats[format].description)) @@ -45,18 +46,15 @@ function list_out_formats() end -@doc """ -Tangle source code from input document to .jl file. - -**parameters:** -```julia +""" tangle(source ; out_path=:doc, informat="noweb") -``` + +Tangle source code from input document to .jl file. * `informat`: `"noweb"` of `"markdown"` * `out_path`: Path where the output is generated. Can be: `:doc`: Path of the source document, `:pwd`: Julia working directory, `"somepath"`: Path as a AbstractString e.g `"/home/mpastell/weaveout"` -"""-> +""" function tangle(source ; out_path=:doc, informat="noweb") doc = read_doc(source, informat) cwd = get_cwd(doc, out_path) @@ -74,14 +72,11 @@ function tangle(source ; out_path=:doc, informat="noweb") info("Writing to file $(doc.basename).jl") end -@doc """ -Weave an input document to output file. - -**parameters:** -```julia +""" weave(source ; doctype = "pandoc", plotlib="Gadfly", informat="noweb", out_path=:doc, fig_path = "figures", fig_ext = nothing) -``` + +Weave an input document to output file. * `doctype`: see `list_out_formats()` * `plotlib`: `"PyPlot"`, `"Gadfly"`, or `"Winston"` @@ -95,7 +90,7 @@ weave(source ; doctype = "pandoc", plotlib="Gadfly", `:user` = cache based on chunk options, `:refresh`, run all code chunks and save new cache. **Note:** Run Weave from terminal and not using IJulia, Juno or ESS, they tend to mess with capturing output. -""" -> +""" function weave(source ; doctype = "pandoc", plotlib="Gadfly", informat="noweb", out_path=:doc, fig_path = "figures", fig_ext = nothing, cache_path = "cache", cache=:off) diff --git a/src/readers.jl b/src/readers.jl index 345d512..c6cfe3c 100644 --- a/src/readers.jl +++ b/src/readers.jl @@ -13,14 +13,14 @@ const input_formats = @compat Dict{AbstractString, Any}( ) -@doc "Read and parse input document" -> +"""Read and parse input document""" function read_doc(source::AbstractString, format="noweb"::AbstractString) document = readall(source) parsed = parse_doc(document, format) doc = WeaveDoc(source, parsed) end -@doc "Parse chunks from AbstractString" -> +"""Parse chunks from AbstractString""" function parse_doc(document::AbstractString, format="noweb"::AbstractString) #doctext = readall(open(document)) lines = split(document, "\n") diff --git a/src/run.jl b/src/run.jl index 73bd30c..acd66e9 100644 --- a/src/run.jl +++ b/src/run.jl @@ -1,11 +1,9 @@ -@doc """ -Run code chunks and capture output from parsed document. - -```julia -function run(doc::WeaveDoc; doctype = "pandoc", plotlib="Gadfly", informat="noweb", +""" +run(doc::WeaveDoc; doctype = "pandoc", plotlib="Gadfly", informat="noweb", out_path=:doc, fig_path = "figures", fig_ext = nothing, cache_path = "cache", cache = :off) -``` + +Run code chunks and capture output from parsed document. * `doctype`: see `list_out_formats()` * `plotlib`: `"PyPlot"`, `"Gadfly"`, or `"Winston"` @@ -19,7 +17,7 @@ function run(doc::WeaveDoc; doctype = "pandoc", plotlib="Gadfly", informat="nowe `:user` = cache based on chunk options, `:refresh`, run all code chunks and save new cache. **Note:** Run command from terminal and not using IJulia, Juno or ESS, they tend to mess with capturing output. -""" -> +""" function Base.run(doc::WeaveDoc; doctype = "pandoc", plotlib="Gadfly", informat="noweb", out_path=:doc, fig_path = "figures", fig_ext = nothing, cache_path = "cache", cache = :off)