Docs on config setup #532

Activity

1. stan-dot

   changed the title [-] examples in the docs without having to read through the code would be helpful for setting up new environments.[/-] [+] examples in the docs[/+] on Jul 1, 2024
2. callumforrester commented on Jul 1, 2024

   

   callumforrester

   on Jul 1, 2024

   Contributor

   More actions

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

   changed the title [-] examples in the docs[/-] [+] examples of the ophyd-async device creation process and reasoning[/+] on Jul 2, 2024
4. callumforrester commented on Sep 5, 2024

   

   callumforrester

   on Sep 5, 2024

   Contributor

   More actions

   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.

   👍React with 👍1Reacted by Stan
5. stan-dot commented on Sep 9, 2024

   

   stan-dot

   on Sep 9, 2024

   ContributorAuthor

   More actions

   what do you think @tpoliaw ?
6. tpoliaw commented on Sep 9, 2024

   

   tpoliaw

   on Sep 9, 2024

   Contributor

   More actions

   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.
7. callumforrester commented on Sep 9, 2024

   

   callumforrester

   on Sep 9, 2024

   Contributor

   More actions

   ...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?
8. stan-dot

   changed the title [-] examples of the ophyd-async device creation process and reasoning[/-] [+]Docs on config setup[/+] on Sep 9, 2024
9. stan-dot

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   enhancementNew feature or requestNew feature or request

   on Sep 9, 2024
10. stan-dot commented on Sep 9, 2024

    

    stan-dot

    on Sep 9, 2024

    ContributorAuthor

    More actions

    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 ?
11. tpoliaw commented on Sep 9, 2024

    

    tpoliaw

    on Sep 9, 2024

    Contributor

    More actions

    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
12. callumforrester commented on Sep 9, 2024

    

    callumforrester

    on Sep 9, 2024

    Contributor

    More actions

    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.
13. stan-dot commented on Sep 9, 2024

    

    stan-dot

    on Sep 9, 2024

    ContributorAuthor

    More actions

    @callumforrester would a test with a hard-coded yml string asserting a correct read be ok?
14. callumforrester commented on Sep 9, 2024

    

    callumforrester

    on Sep 9, 2024

    Contributor

    More actions

    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.
15. stan-dot commented on Sep 9, 2024

    

    stan-dot

    on Sep 9, 2024

    ContributorAuthor

    More actions

    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

    👍React with 👍1Reacted by Callum Forrester
16. stan-dot

    self-assigned this

    on Sep 11, 2024
17. stan-dot

    linked a pull request that will close this issueConfig setup docs - through tests #634on Sep 12, 2024
18. stan-dot

    closed this as completedin #634on Oct 30, 2024
19. callumforrester commented on Oct 31, 2024

    

    callumforrester

    on Oct 31, 2024

    Contributor

    More actions

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

    reopened this on Oct 31, 2024
21. abbiemery commented on Feb 25, 2026

    

    abbiemery

    on Feb 25, 2026

    Contributor

    More actions

    Closing in favour of #1416
22. abbiemery

    closed this as completedon Feb 25, 2026
23. abbiemery

    closed this as a duplicateof Add getting-started docs covering configuration #1416 on Feb 25, 2026