feat: refactor hooks API for simplification

[regisb]

The hooks API had several issues which are summarized in this comment: openedx-unsupported/wg-developer-experience#125 (comment)

1. "consts" was a bad name
2. "hooks.filters" and "hooks.Filters" could easily be confused
3. docs made it difficult to understand that plugin developers should use the catalog

To address these issues, we:

1. move "consts.py" to "catalog.py"
2. Remove "hooks.actions", "hooks.filters", "hooks.contexts" from the API.
3. re-organize the docs and give better usage examples in the catalog.

This change is a partial fix for openedx-unsupported/wg-developer-experience#125

[kdmccormick]

At a glance, I like the look of this. I can take a closer look next week.

[kdmccormick]

I have some suggestions, but even without applying any them, I think this is a good improvement. Thanks for all your work here!

[regisb]

Please check out my changes in the latest commit @kdmccormick: 9522785

[regisb]

Sphinx has given me hell with the new typing annotations... It's been crazy hard to get the docs to build across different Python version, to the point that I considered switching to a different documentation backend entirely.
At this point, the docs no longer build on Python 3.10. Here are the errors that I'm getting:

/home/data/regis/projets/overhang/repos/overhang/tutor/tutor/hooks/catalog.py:docstring of tutor.hooks.Actions.COMPOSE_PROJECT_STARTED:1: WARNING: py:class reference target not found: tutor.core.hooks.actions.Action[(<class 'str'>, typing.Dict[str, typing.Union[str, float, NoneType, bool, typing.List[str], typing.List[typing.Any], typing.Dict[str, typing.Any], typing.Dict[typing.Any, typing.Any]]], <class 'str'>)]
/home/data/regis/projets/overhang/repos/overhang/tutor/tutor/hooks/catalog.py:docstring of tutor.hooks.Actions.DO_JOB:1: WARNING: py:class reference target not found: tutor.core.hooks.actions.Action[(<class 'str'>, typing.Any)]
/home/data/regis/projets/overhang/repos/overhang/tutor/tutor/hooks/catalog.py:docstring of tutor.hooks.Actions.PLUGIN_UNLOADED:1: WARNING: py:class reference target not found: tutor.core.hooks.actions.Action[(<class 'str'>, <class 'str'>, typing.Dict[str, typing.Union[str, float, NoneType, bool, typing.List[str], typing.List[typing.Any], typing.Dict[str, typing.Any], typing.Dict[typing.Any, typing.Any]]])]
/home/data/regis/projets/overhang/repos/overhang/tutor/tutor/hooks/catalog.py:docstring of tutor.hooks.Actions.PROJECT_ROOT_READY:1: WARNING: py:class reference target not found: tutor.core.hooks.actions.Action[(<class 'str'>,)]
/home/data/regis/projets/overhang/repos/overhang/tutor/tutor/hooks/catalog.py:docstring of tutor.hooks.Filters.COMPOSE_MOUNTS:1: WARNING: py:class reference target not found: tutor.core.hooks.filters.Filter[list[tuple[str, str]], (<class 'str'>,)]

For the record, these errors come from the recent type annotations PR, not from this API simplification PR.

If anyone wants to give a stab at building the docs on Python 3.10, they are more than welcome.

[regisb]

@kdmccormick I know that this PR has grown to a humongous scale and I hate to ask this from you, but could you please have another look at this PR? If not it's OK, I think I can merge as it is.

[kdmccormick]

@regisb Instead of driving ourselves crazy with convincing Sphinx to accept the type annotations on every supported Python version, can we choose 1 specific Python version to support for Tutor development (docs, linting, typechecking)? I use a virtualenv whenever I hack on Tutor, anyway, as I'm sure most folks do.

Then, for the greater set of 3-4 supported Python versions, we'd just need to worry about the code itself running and unit tests passing.

We're just asking a lot of ourselves if we want docs+linting+types+tests to all pass on 3-4 different Python versions, even though PRs only run checks for one version.

could you please have another look at this PR?

Sure thing, I'll take a look today.

[regisb]

can we choose 1 specific Python version to support for Tutor development (docs, linting, typechecking)?

I guess it would make sense, yes. The problem is that I'd rather default to the newest stable Python version (3.11) but the docs don't build on 3.11 either. Next step will probably be to ask a question on stackoverflow...

[kdmccormick]

Sorry that I did not get to re-reviewing this. It's at the top of my priority list for Monday.

[kdmccormick]

The API and the docs are looking better and better. Sorry that Sphinx has been such a PITA. For what it's worth, the build is passing on for me on Python 3.9, too.

[regisb]

Thanks a lot for the many reviews Kyle! I applied your recommendations and will merge this now.