Start moving docs to docstrings

doc/README.md

@@ -0,0 +1 @@
+`genrst.jl` generates the rst files from Julia docstrings. This should be run *before* committing the changes to the repository.

doc/genrst.jl

@@ -0,0 +1,55 @@
+using Distributions
+
+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
+
+cd(joinpath(dirname(@__FILE__),"source")) do
+    for (name,T) in [("Univariate Discrete",DiscreteUnivariateDistribution),
+                     ("Univariate Continuous",ContinuousUnivariateDistribution),
+                     ]
+
+        fname = replace(lowercase(name),' ','-')
+        open("$fname.rst","w") do f
+            println(f,".. _$fname:")
+            println(f)
+            println(f,"$name Distributions")
+            println(f,"----------------------------------------------------")
+            println(f)
+            println(f, ".. DO NOT EDIT: this file is generated from Julia source.")
+            println(f)
+
+            for D in subtypes(T)
+                if isleaftype(D)
+                    md = Base.doc(D)
+                    if isa(md,Markdown.MD)
+                        isa(md.content[1].content[1],Markdown.Code) || error("Incorrect docstring format: $D")
+
+                        printrst(f,md)
+                    else
+                        warn("$D is not documented.")
+                    end
+                end
+            end
+        end
+    end
+end

doc/source/conf.py

@@ -25,7 +25,9 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath']
+extensions = ['sphinx.ext.mathjax',
+              'sphinx.ext.todo',
+              'sphinx.ext.coverage']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -34,7 +36,7 @@
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'