📚 Docs preview built and uploaded! https://www.fastplotlib.org/ver/docs-events-detailed

@clewis7 replacing all hard-coded rst event info tables with list of dicts, more maintainable, easy to parse it into a table for docs.

class VertexPositions(BufferManager):
    property_name = "data"
    event_info_spec = [
        {
            "dict key": "key",
            "type": "slice, index (int) or numpy-like fancy index",
            "description": "key at which vertex positions data were indexed/sliced"
        },
        {
            "dict key": "value",
            "type": "int | float | array-like",
            "description": "new data values for points that were changed"
        },
    ]

I copy-pasted some code from here, it works: https://pablofernandez.tech/2019/03/21/turning-a-list-of-dicts-into-a-restructured-text-table/

Thoughts for making classes under graphics.features public:

• Keep the name GraphicFeature, no renaming to GraphicProperty because then that confuses it with the actual properties on the graphics. A GraphicFeature is different from the actual property attributes on a Graphic which are the user-facing properties to modify a GraphicFeature.
• Rename FeatureEvent to GraphicFeatureEvent ? More explicit.
• Expose GraphicFeatureEvent at top level, i.e. fpl.GraphicFeatureEvent. Very useful for type annotations of event handlers.
• Users will not need to use GraphicFeature classes, except for advanced users who want to make their own Graphic classes etc. I cannot think of a case where a standard user would need access to a GraphicFeature class. So, although we make graphic feature classes part of the public API it will need to be accessed explicitly, ex: from fastplotlib.graphics.features import VertexColors

@clewis7

Thoughts for making classes under graphics.features public:

• Keep the name GraphicFeature, no renaming to GraphicProperty because then that confuses it with the actual properties on the graphics. A GraphicFeature is different from the actual property attributes on a Graphic which are the user-facing properties to modify a GraphicFeature.
• Rename FeatureEvent to GraphicFeatureEvent ? More explicit.
• Expose GraphicFeatureEvent at top level, i.e. fpl.GraphicFeatureEvent. Very useful for type annotations of event handlers.
• Users will not need to use GraphicFeature classes, except for advanced users who want to make their own Graphic classes etc. I cannot think of a case where a standard user would need access to a GraphicFeature class. So, although we make graphic feature classes part of the public API it will need to be accessed explicitly, ex: from fastplotlib.graphics.features import VertexColors

@clewis7

I like keeping the name the same. I also like GraphicFeatureEvent because it is more explicit.

Aside from type annotations, when would a user need fpl.GraphicFeatureEvent? If it is just for that, I am not sure we should expose it...maybe better to just have really good docs.

I like the explicit access of a GraphicFeature just because I agree no one would ever need it unless they were doing something custom.

Aside from type annotations, when would a user need fpl.GraphicFeatureEvent? If it is just for that, I am not sure we should expose it...maybe better to just have really good docs.

Earlier we kinda came to the conclusion that anything which is use ~80% of the time should be a top level import, and event it's used for type annotations it's still very useful and events are used very often so I've made it a top level import. It's a pretty clean import so there aren't issues with doing this.

@clewis7 should be gtg!

summary of major changes other than those already mentioned above:

1. Cleaned up events docs section in user guide, graphic feature event tables are now auto-generated and in their own section: https://www.fastplotlib.org/ver/docs-events-detailed/user_guide/event_tables.html. The auto generation is done based on this: more event docs, make some things public #773 (comment)
2. Added UI library integration section in guide.
3. Examples gallery:
   • controller examples
   • event examples
   • moving text example
4. Graphic._features is now a dict instead of a set which maps the graphic property name to the feature class. Right now this mapping is only used for generating the graphic feature event tables in the docs. See here. It's private so no changes to the user.

Tested all examples and they work!