Doc milestone

doc/genrst.jl

@@ -0,0 +1,131 @@
+####################
+# Helper functions #
+####################
+
+if VERSION < v"0.5.0-"
+    function Markdown.rstinline(io::IO, md::Markdown.Link)
+        if ismatch(r":(func|obj|ref|exc|class|const|data):`\.*", md.url)
+            Markdown.rstinline(io, md.url)
+        else
+            Markdown.rstinline(io, "`", md.text, " <", md.url, ">`_")
+        end
+    end
+end
+
+function printrst(io,md)
+    mdd = md.content[1]
+    sigs = shift!(mdd.content)
+
+    decl = ".. function:: "*replace(sigs.code, "\n","\n              ")
+    body = Markdown.rst(mdd)
+    println(io, decl)
+    println(io)
+    for l in split(body, "\n")
+        ismatch(r"^\s*$", l) ? println(io) : println(io, "   ", l)
+    end
+end
+
+#########################
+# Main auto-gen routine #
+#########################
+
+using Turing  # load the package to bind docs
+
+#######################################################################
+# NOTE: this is the to-generate list.                                 #
+# Each key-value mapping will be convereted into a .rst file.         #
+# :title is the title of this .rst file, and                          #
+# :list contains APIs to be generated.                                #
+to_gen = Dict(                                                        #
+  "replayapi" => Dict(                                                #
+    :title  =>  "Replay",                                             #
+    :list   =>  ["Prior", "PriorArray", "PriorContainer", "addPrior"] #
+  ),                                                                  #
+  "compilerapi" => Dict(                                              #
+    :title  =>  "Compiler",                                           #
+    :list   =>  ["@assume", "@observe", "@predict", "@model"]         #
+  ),                                                                  #
+  "samplerapi" => Dict(                                               #
+    :title  =>  "Sampler",                                            #
+    :list   =>  ["IS", "SMC", "PG", "HMC"]                            #
+  ),                                                                  #
+  "tarrayapi" => Dict(                                                #
+    :title  =>  "TArray",                                             #
+    :list   =>  ["TArray", "tzeros"]                                  #
+  ),                                                                  #
+  "chainapi" => Dict(                                                 #
+    :title  =>  "Chain",                                              #
+    :list   => ["Chain", "Sample"]                                    #
+  )                                                                   #
+)                                                                     #
+#######################################################################
+
+# Generate all APIs
+cd(joinpath(dirname(@__FILE__),"source")) do
+  for fname in keys(to_gen)
+    open("$fname.rst","w") do f
+      println(f,"$(to_gen[fname][:title])\n=========\n")
+      for api in to_gen[fname][:list]
+        md = include_string("@doc $api")
+        if isa(md,Markdown.MD)
+          isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $api")
+
+          printrst(f,md)
+        else
+          warn("$D is not documented.")
+        end
+      end
+    end
+  end
+end
+
+# Generate API filenames
+fnames = [fname for fname in keys(to_gen)]
+api_str = "$(shift!(fnames))"
+for fname in fnames
+  api_str *= "\n   $fname"
+end
+
+# Generate index.rst
+rst = """
+Welcome to Turing.jl's documentation!
+=====================================
+
+Contents
+^^^^^^^^
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   getstarted
+
+.. toctree::
+   :maxdepth: 2
+   :caption: APIs
+
+   $api_str
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Development Notes
+
+   language
+   compiler
+   samplerintro
+   tarray
+   workflow
+
+.. toctree::
+   :maxdepth: 2
+   :caption: License
+
+   license
+
+"""
+
+cd(joinpath(dirname(@__FILE__),"source")) do
+  open("index.rst","w") do f
+    println(f,rst)
+  end
+end

doc/source/chainapi.rst

@@ -0,0 +1,47 @@
+Chain
+=========
+
+.. function:: Chain(weight::Float64, value::Array{Sample})
+
+   A wrapper of output trajactory of samplers.
+
+   Example:
+
+   .. code-block:: julia
+
+       # Define a model
+       @model xxx begin
+         ...
+         @predict mu sigma
+       end
+
+       # Run the inference engine
+       chain = sample(xxx, SMC(1000))
+
+       chain[:logevidence]   # show the log model evidence
+       chain[:mu]            # show the weighted trajactory for :mu
+       chain[:sigma]         # show the weighted trajactory for :sigma
+       mean(chain[:mu])      # find the mean of :mu
+       mean(chain[:sigma])   # find the mean of :sigma
+
+.. function:: Sample(weight::Float64, value::Dict{Symbol,Any})
+
+   A wrapper of output samples.
+
+   Example:
+
+   .. code-block:: julia
+
+       # Define a model
+       @model xxx begin
+         ...
+         @predict mu sigma
+       end
+
+       # Run the inference engine
+       chain = sample(xxx, SMC(1000))
+
+       sample = chain[:mu][1]  # get the first sample
+       sample.weight           # show the weight of this sample
+       sample.value            # show the value of this sample (a dictionary)
+

doc/source/compilerapi.rst

@@ -0,0 +1,79 @@
+Compiler
+=========
+
+.. function:: assume(ex)
+
+   Operation for defining the prior.
+
+   Usage:
+
+   .. code-block:: julia
+
+       @assume x ~ Dist
+
+   Here ``x`` is a **symbol** to be used and ``Dist`` is a valid distribution from the Distributions.jl package. Optional parameters can also be passed (see examples below).
+
+   Example:
+
+   .. code-block:: julia
+
+       @assume x ~ Normal(0, 1)
+       @assume x ~ Binomial(0, 1)
+       @assume x ~ Normal(0, 1; :static=true)
+       @assume x ~ Binomial(0, 1; :param=true)
+
+.. function:: observe(ex)
+
+   Operation for defining the likelihood.
+
+   Usage:
+
+   .. code-block:: julia
+
+       @observe x ~ Dist
+
+   Here ``x`` is a **concrete value** to be used and ``Dist`` is a valid distribution from the Distributions.jl package. Optional parameters can also be passed (see examples below).
+
+   Example:
+
+   .. code-block:: julia
+
+       @observe x ~ Normal(0, 1)
+       @observe x ~ Binomial(0, 1)
+       @observe x ~ Normal(0, 1; :static=true)
+       @observe x ~ Binomial(0, 1; :param=true)
+
+.. function:: predict(ex...)
+
+   Operation for defining the the variable(s) to return.
+
+   Usage:
+
+   .. code-block:: julia
+
+       @predict x y z
+
+   Here ``x``\ , ``y``\ , ``z`` are symbols.
+
+.. function:: model(name, fbody)
+
+   Wrapper for models.
+
+   Usage:
+
+   .. code-block:: julia
+
+       @model f body
+
+   Example:
+
+   .. code-block:: julia
+
+       @model gauss begin
+         @assume s ~ InverseGamma(2,3)
+         @assume m ~ Normal(0,sqrt(s))
+         @observe 1.5 ~ Normal(m, sqrt(s))
+         @observe 2.0 ~ Normal(m, sqrt(s))
+         @predict s m
+       end
+

docs/source/conf.py → doc/source/conf.py

@@ -30,7 +30,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc', 'juliadoc.julia', 'juliadoc.jlhelp'
+    'juliadoc.julia', 'juliadoc.jlhelp'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -49,8 +49,8 @@
 
 # General information about the project.
 project = u'Turing.jl'
-copyright = u'2016, Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani'
-author = u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani'
+copyright = u'2016, Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani, Kai Xu'
+author = u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani, Kai Xu'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -111,8 +111,8 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme = 'julia'
-html_theme = 'alabaster'
+html_theme = 'julia'
+# html_theme = 'alabaster'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -229,7 +229,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'Turingjl.tex', u'Turing.jl Documentation',
-     u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani', 'manual'),
+     u'Hong Ge, Adam Scibior, Matej Balog, Zoubin Ghahramani, Kai Xu', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of