User guide examples for bokeh server and django

[ceball]

Not yet ready to review, except for two bits I'd like feedback on already:

1. The example used to demonstrate parambokeh + bokeh server: see code in examples/apps/bokeh/simple.py

2. How to include the example app code in the notebook? You can see in the examples/user_guide/Bokeh_App notebook I've added a hack to be able to display each bit of the file as I talk about it...

I could instead just copy/paste bits. Or I could not refer to the example specifically at all; just describe how to use parambokeh in bokeh server, and then at the end say "for a concrete example, see ...". Or maybe there's something better I could do?

[jbednar]

Looks good to me; it's hard to say without seeing it presented as an example. In the https://github.com/pyviz/pyviz/blob/master/notebooks/A2_Dashboard_Workflow.ipynb notebook, you can see that I handled the partial-app issue by introducing each bit of code on its own in the notebook, showing how each bit works, and only then showed the separate full app by dumping the file onscreen. The code in the snippets and the app then drift our of sync over time, of course, but at least the snippets let people understand it bit by bit and try it themselves. As you wish!

[jbednar]

Not sure "Usage in" adds anything here or below.

[ceball]

Agreed

[ceball]

it's hard to say without seeing it presented as an example. In the https://github.com/pyviz/pyviz/blob/master/notebooks/A2_Dashboard_Workflow.ipynb notebook, you can see that I handled the partial-app issue by introducing each bit of code on its own in the notebook, showing how each bit works, and only then showed the separate full app by dumping the file onscreen. The code in the snippets and the app then drift our of sync over time, of course, but at least the snippets let people understand it bit by bit and try it themselves.

Maybe it's clearer if you look at the source only notebook?

https://github.com/ioam/parambokeh/blob/e27f7baa77039f20e8044476b146b807c040f279/examples/user_guide/Bokeh_App.ipynb

This approach does introduce the example bit by bit. It's just in desperation to avoid duplicating the code (which will inevitably go out of date as you say...), I have resorted to a hack (which would need to be hidden/imported from elsewhere).

Combined with the screenshot in the original comment above, which shows how it looks when the notebook is run (the code's there and can be copy/pasted etc), I think that should let you see the pros and cons.

Probably I vote for just doing what you did, and copy/pasting the code into the notebook.

[ceball]

If the website builds ok, I will merge. There are definitely improvements we could make to this documentation, but it's ready to receive user feedback, plus some improvement will come separately from reviewing the entire documentation after #61 is merged and when we switch to the new (still upcoming) release of nbsite (because the website editing process should then be easier, encouraging us to make the improvements).