DOC/MAINT: add documentation, docking system conda shim #128
Conversation
ZLLentz
changed the title
ZLLentz
changed the title
|
I'm now fairly confident this is correct and useful. In about 5 mins the GHA will build the docs again which is the preferred way to review the html. |
There was a problem hiding this comment.
I like the docs. I do think pictures would be immensely helpful but if we're going to be revamping the config system soon it's probably fine to not polish this too thoroughly.
A couple of thoughts I had while reading through the docs, I do feel like these are even more optional suggestions than normal.
docs/source/grid.rst
Outdated
| LUCID Grid Configuration | ||
| ======================== | ||
|
|
||
| ``LUCID``'s main grid area is an auto-generated series of buttons and indicators, |
There was a problem hiding this comment.
| ``LUCID``'s main grid area is an auto-generated series of buttons and indicators, | |
| ``lucid``'s main grid area is an auto-generated series of buttons and indicators, |
Should we keep this consistent throughout the docs?
There was a problem hiding this comment.
I'm trying to use LUCID when talking about the app and lucid when talking about the cli invocation, but:
- I may not have done this correctly in general
- This might not be the right approach
I'm tempted to turn it all into lucid in general and Lucid in titles
There was a problem hiding this comment.
A lot of this stems from the readme and docs previously using LUCID exclusively despite the lowercase cli entrypoint + my dislike of all caps or special caps names in general
There was a problem hiding this comment.
I feel like my opinion on the matter changes daily. I think it's fine as is, it just stuck out as the only fully-capitalized instance on the page
There was a problem hiding this comment.
I'm going to go ahead and change it to my preferences of Lucid or lucid everywhere (down with arbitrary casing!). I think this is noncontroversial because Lucid is essentially a normal word despite being an acronym.
Co-authored-by: Robert Tang-Kong <[email protected]>
|
RE: pictures:
But I think these are both worth doing |
|
I found an image of lucid on confluence, so I'm going to edit it a bit and use it here to have one simple visual on each of these two pages |
|
snapshot of how the two new pages look with the images: |
docs/source/grid.rst
Outdated
| - ``functional_group``, to select with row to put a device into | ||
|
|
||
| That is to say, by default we expect the row headers on the left to be functional names like | ||
| "imager" or "vacuum" and column headers on the top to be location names like "SB3" or "VLS". |
There was a problem hiding this comment.
| "imager" or "vacuum" and column headers on the top to be location names like "SB3" or "VLS". | |
| "imager" or "vacuum" and column headers on the top to be location names like "Section 01" or "Section 02". |
I like the docs a lot better with pictures, one last nitpick might be to make the examples match the images.
We could take this a step further with the buttons config, but if we do I'd advocate showing two configs. One with the descriptive values and one that matches the toolbar shown in the image.
There was a problem hiding this comment.
I think I'm not motivated to make an example config that matches the image, I'd be better off redoing the images to be the current config and pasting the current KFE config in.
Instead, I'll add a link to the lucid configs backup repo (which I'll update again at some point) so at least there's a way to see a bunch of valid configs.
I'm also going to merge your suggestion here
Co-authored-by: Robert Tang-Kong <[email protected]>
closes #125
I intended to test this offline but couldn't quickly get the docs building on my local windows machine, so I'm going to iterate by downloading the CI docs build generated from this PR and checking that it looks normal.