Document ContextKeys

[Carreau]

From napari/napari#4499,

I do no see update of guides/context_expressions.md in this PR, but this file contains table of example context keys that will be outdated after this PR merge. Could you update it?

Is there place where all context keys are documented? or only code and PR comments (I'm not familiar with this part of napari code)?

Originally posted by @Czaki in napari/napari#4499 (review)

@talmbert03 later replied:

That doc can be considered internal for napari core devs (as stated at the top). I do have a plan for (auto)generating front facing docs using the descriptions jn these ContextKey objects... But until a plugin can actually take advantage of these keys using when conditions, we're not going to break anything by changing these here

As we may have this document auto generated and the plugins do not yet have access to those values, I think we can postpone the documentation update and move forward with the code.

[tlambert03]

yep. just to reiterate, that doc is not meant to be the place where people go to see the keys in that file. It is not intended to be kept in sync with any specific set of context keys. It's a conceptual document for napari devs to understand what context keys even are, (not a reference for what keys are valid)

[Carreau]

Thanks, I had the impression that these comments in the napari/napari#4499 review were the blocking one, so I opened. this just to be safe. It's easy to close later if we want. Especially since GH now have "close as not planned".

[lucyleeow]

Could we update the title of this issue to be about documenting context keys (as they are not meant to be documented in context_expressions.md), e.g., "Document ContextKeys". I don't have rights in this repo to edit.

We don't currently have a place for context key documentation. We also need to decide if we want to autogenerate the docs and if so, how.

ping @melissawm or @psobolewskiPhD (I think you both have rights)

[lucyleeow]

Just wanted to update this after discussion with @melissawm at the docs meeting:

@melissawm suggested that we could something similar to what is done in docs/_scripts/update_preference_docs.py to get the description text given in the ContextKey definitions and auto doc the keys.

Context keys are not exposed publicly yet though. I think we eventually would expose them as part of NAP-6 (when for menu and enablement for commands) but this has not happened yet.

cc @DragaDoncila