Document the language

[stuhlmueller]

Possibly in part automatically: #87

[null-a]

Keep in mind that we plan to change the interface to inference algorithms. (#86)

[stuhlmueller]

One option is to write the docs in rst (or markdown), and then auto-build and host using readthedocs. This is what Julia does.

[stuhlmueller]

As part of this process, I'd also move some of the information that's currently in the README to the documentation.

[null-a]

Core inference algorithms are now documented. Documenting ERPs is issue #87.

[null-a]

@ngoodman made a start on this.

[chrisranderson]

Working on getting everything in header.wppl into the docs. I'll start with at least listing the function, then try to get explanations, then go for examples after that (if you'd like them).

[null-a]

Update: Things have changed, and I'm not this makes much sense anymore. Don't waste your time reading it...

@ngoodman made a start on this.

Looking at this, I get the impression that there are only a few bits we are short of for an initial pass of this. I'm thinking I could do the following:

Introduction to sample, factor, marginalization

We probably need to explain how sample, factor, distributions, inference fit together somewhere, but this already exists in dippl and agent models.

The "Learning" section in "Quick Start" already points to the dippl version of this. We can perhaps make this a little more obvious by moving the installation instructions out of the quick start page. (As suggested by @stuhlmueller here.)

Having skimmed through these, I think the agent models intro may be the most suitable of the two to link to eventually, but at the moment it still talks about ERP.

Language reference

Add a "language reference" page with the full list of JS syntax used in webppl. (Already exists in dippl.)

It seems useful (?) to have this around in a place that's easy to point people at. It probably doesn't need to be the first thing people see though.

Reference docs for sample, factor etc.

Perhaps we should have reference docs for sample, factor, etc. These would be similar to the current header function docs.

We need the introduction to get people started, but once people are familiar with the language it may be useful to have a concise list of primitives somewhere to make it possible to see everything at a glance, quickly check params, etc.

~~The current paragraph on "guides" could then fit under the sample reference docs.~~ (Actually, this won't work since we also have the "Drift Kernels" section which wouldn't comfortably fit here.)

We could include these on the current "Header" page, or create a new "Primitives" page/section if we think it makes sense to make the distinction. I think we should probably just add these somewhere, and move them around later as necessary.

Javascript Interop

Make a new page and just copy the dippl paragraph on calling JS functions, and the restrictions in doing so. I don't think this belongs in the packages section because it also applies to built in JS functions.

Any thoughts?

[mhtess]

FWIW, I wrote some (very simple) webppl tutorials this summer for various demos: basic programming with webppl and introduction to bayes rule with rejection

[null-a]

I decided to spend some time focused on getting the ideas from the "Distributions, sampling, factor, inference" section of Noah's sketch integrated into the docs.

#591 was one part of this.

The other part I'm not so sure about... you can see it here. The general idea here is to expand the introduction to inference a little and include a brief mention of factor.

In the spirit of Noah's sketch, I've intentionally tried to keep this brief. Brevity in the docs seems like a good thing to me -- we can link to tutorial material elsewhere as required.

Any thoughts? Is this a useful addition as it is? If not, is this even heading in vaguely the right direction?

[ngoodman]

i think this is useful! i think we should get it (and the other docs changes) merged, and then i will take a look over everything and adjust wording if i think it's needed.

[null-a]

i think this is useful! i think we should get it (and the other docs changes) merged, and then i will take a look over everything and adjust wording if i think it's needed.

Great stuff. I took another pass myself, and submitted #597.

[stuhlmueller]

Also, document the new model shorthand syntax in Infer (see discussion in #692).