DOC: Answer two common questions.

[danielballan]

Answer two common questions.

Rendered here for easier reading:

[mrakitin]

Nice work! Left a few comments with suggestions.

[tacaswell]

I am wary of this code block because it will be copy-pasted into a plan.

[mrakitin]

👍

[prjemian]

I agree with Tom. Suggest replacing lines 124-128 with this:

We recommend either setting the time-related parameter(s) in advance.
For interactive use:

   .. code-block:: python

      det.exposure_time.set(3)

From a plan:

   .. code-block:: python

      yield from bluesky.plan_stubs.mv(det.exposure_time, 3)

[prjemian]

Perfect place to expand on why a common method is a challenge. Add this paragraph:

Scalers also parametrize exposure time with *multiple*
parameters.  The most common term (used by 
`EpicsScaler` and `ScalerCH`) is `det.preset_time`.

Do multi-channel analyzers and multi-channel scalers set the time differently. This is the place to mention briefly.

[danielballan]

This is a surprising test failure:

=================================== FAILURES ===================================

�[31m�[1m________________________________ test_per_step _________________________________�[0m



RE = <bluesky.run_engine.RunEngine object at 0x1248d6e48>

hw = namespace(ab_det=ABDetector(prefix='', name='det', read_attrs=['a', 'b'], configuration_attrs=[]), bool_sig=Signal(nam...Signal(name='sig', value=0, timestamp=1561990333.873343), trivial_flyer=<ophyd.sim.TrivialFlyer object at 0x126781518>)



�[1m    def test_per_step(RE, hw):�[0m

�[1m        # Check default behavior, using one motor and then two.�[0m

�[1m        RE(scan([hw.det], hw.motor, -1, 1, 3, per_step=one_nd_step))�[0m

�[1m        RE(scan([hw.det],�[0m

�[1m                hw.motor, -1, 1,�[0m

�[1m                hw.motor2, -1, 1,�[0m

�[1m                3,�[0m

�[1m                per_step=one_nd_step))�[0m

�[1m        RE(inner_product_scan([hw.det], 3, hw.motor, -1, 1, per_step=one_nd_step))�[0m

�[1m        RE(inner_product_scan([hw.det],�[0m

�[1m                              3,�[0m

�[1m                              hw.motor, -1, 1,�[0m

�[1m                              hw.motor2, -1, 1,�[0m

�[1m                              per_step=one_nd_step))�[0m

�[1m    �[0m

�[1m        # Check that scan still accepts old one_1d_step signature:�[0m

�[1m        RE(scan([hw.det], hw.motor, -1, 1, 3, per_step=one_1d_step))�[0m

�[1m        RE(rel_scan([hw.det], hw.motor, -1, 1, 3, per_step=one_1d_step))�[0m

�[1m    �[0m

�[1m        # Test that various error paths include a useful error message identifying�[0m

�[1m        # that the problem is with 'per_step':�[0m

�[1m    �[0m

�[1m        # You can't usage one_1d_step signature with more than one motor.�[0m

�[1m        with pytest.raises(TypeError) as exc:�[0m

�[1m            RE(scan([hw.det],�[0m

�[1m                    hw.motor, -1, 1,�[0m

�[1m                    hw.motor2, -1, 1,�[0m

�[1m                    3,�[0m

�[1m                    per_step=one_1d_step))�[0m

�[1m>       assert "Signature of per_step assumes 1D trajectory" in str(exc)�[0m

�[1m�[31mE       AssertionError: assert 'Signature of per_step assumes 1D trajectory' in '<ExceptionInfo TypeError tblen=7>'�[0m

�[1m�[31mE        +  where '<ExceptionInfo TypeError tblen=7>' = str(<ExceptionInfo TypeError tblen=7>)�[0m



�[1m�[31mbluesky/tests/test_new_examples.py�[0m:676: AssertionError

[danielballan]

Hm, also seeing this failure on other recent PRs. Very strange.

[danielballan]

OK, problem identified and fixed in #1225. Unrelated to this change.