Docs on config setup

[stan-dot]

That would be good as well, but I think having examples in the docs without having to read through the code would be helpful for setting up new environments.

Originally posted by @tpoliaw in #408 (comment)

[callumforrester]

@stan-dot could you add more description/context to this issue please?

[callumforrester]

This has been done in the dodal and ophyd-async documentation. I think we should close this issue, or at most just include links in the blueapi docs.

[stan-dot]

what do you think @tpoliaw ?

[tpoliaw]

I still think there needs to be something prominent in the docs/ getting started that details what should go in the config file. It currently says use blueapi --config path/to/file.yaml to pass configuration but not what should go in the file, only that "An example of this yaml file is found in config/defaults.yaml" which no longer exists.

[callumforrester]

...true, reading your original comment, I think the title of this issue may just be wrong. @stan-dot could you rename it to be about the blueapi config, rather than ophyd-async devices?

[stan-dot]

I think to add

env:
  sources:
    - kind: dodal
      module: dodal.beamlines.p38
    - kind: planFunctions
      module: dls_bluesky_core.plans
    - kind: planFunctions
      module: dls_bluesky_core.stubs
  data_writing:
    visit_directory: /dls/p38/data/2023/cm33874-1
    group_name: BL38P

to blueapi.config.ConfigLoader as docstring. What do you think @tpoliaw , @callumforrester ?

[tpoliaw]

That would be a useful start. Do the docstrings end up on the docs site somewhere? It would be good if there was detail about what the various kinds were as well as where it is looking for modules etc. It would be good to add a link to the cli as well so that blueapi --help will direct users to something useful

[callumforrester]

Yeah, it would be good to have a reference here: https://diamondlightsource.github.io/blueapi/main/reference.html

@stan-dot A complete example would be good but it would be ideal if we didn't have to rely on a human to remember to keep it up-to-date. I.e. we should make an example in code, generate some yaml for the docs from it, and that way it should fail if we ever change the config model and cause a validation error.

[stan-dot]

@callumforrester would a test with a hard-coded yml string asserting a correct read be ok?

[callumforrester]

I would accept that, although I would personally prefer the other way around (generate the yml string from hard-coded python), but for no other reason than it seems neater.

[stan-dot]

getting the raw yml string is more similar to parsing a raw .yml file contents from the filesystem (the previous setup). I'll make the new test soon

[callumforrester]

I'm not sure if the acceptance criteria have been met since @tpoliaw asked for examples in the docs, not the tests