improve documentation

fixes #1391

and add improvements/fixes to documentation
I was going to ask @Maggie-M to update the `file` examples to match the `server` examples (the server examples will break if `output_server` is moved below the plotting commands, unfortunately)