DOC: Ophyd Doc Improvements

[teddyrendahl]

I saw in https://github.com/NSLS-II/ophyd/issues/467 there will be a documentation effort for ophyd and wanted to add my two cents. I really liked how bluesky had a user and developer sections and always wanted the same for ophyd. I think this a) helped users get used to usingbluesky very quickly b) promoted standards for developers creating scans. A lot of this is based on what we at SLAC originally struggled with when trying to create our own ophyd devices. Here is a little outline I wrote about what I feel is missing:

• User Guide

  • Basic functionality
    • read, set, trigger e.t.c
  • How to use status objects
  • How to use Subscriptions

• Developers Guide

  • Device Creation
    • Component types
      • DynamicDeviceComponent especially
        • Signal types
      • AttributeSignal, DerivedSignal especially
  • Positioners
    • Be explicit about requirements for creating custom Positioner objects
  • How to create subscriptions
  • How to create useful status objects

I was going to try and write some of this up myself. For SLAC I wanted to create a style guide kind of thing so that we are at least internally consistent about how we create our objects. I figured it might be useful to the community as well.

[danielballan]

Yeah, the bluesky documentation got at least three rewrites and informal word-by-word reviews with users from various perspectives. These suggestions from you are super useful as I begin that process for ophyd.

I think I might try organizing the docs along the lines of what I did with caproto -- a clear split between teaching-by-narrative-and-example and straight API docs. I'll push early and solicit some feedback/contributions if you have time to collaborate on it. I really like the idea of a style guide.

[danielballan]

Noting this here so it doesn't get lost: we should link to the experimental project https://github.com/klauer/recordwhat to make it a bit more discoverable. (h/t @prjemian)