christianlight/tutor
6
0
Fork 0
mirror of https://github.com/ChristianLight/tutor.git synced 2024-12-13 14:43:03 +00:00
Code Issues Releases Activity
6257c1c7ac
tutor/docs/plugins/intro.rst

69 lines
3.0 KiB
ReStructuredText
Raw Normal View History

Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
.. _plugins:
feat: migrate to plugins.v1 with filters & actions This is a very large refactoring which aims at making Tutor both more extendable and more generic. Historically, the Tutor plugin system was designed as an ad-hoc solution to allow developers to modify their own Open edX platforms without having to fork Tutor. The plugin API was simple, but limited, because of its ad-hoc nature. As a consequence, there were many things that plugin developers could not do, such as extending different parts of the CLI or adding custom template filters. Here, we refactor the whole codebase to make use of a generic plugin system. This system was inspired by the Wordpress plugin API and the Open edX "hooks and filters" API. The various components are added to a small core thanks to a set of actions and filters. Actions are callback functions that can be triggered at different points of the application lifecycle. Filters are functions that modify some data. Both actions and filters are collectively named as "hooks". Hooks can optionally be created within a certain context, which makes it easier to keep track of which application created which callback. This new hooks system allows us to provide a Python API that developers can use to extend their applications. The API reference is added to the documentation, along with a new plugin development tutorial. The plugin v0 API remains supported for backward compatibility of existing plugins. Done: - Do not load commands from plugins which are not enabled. - Load enabled plugins once on start. - Implement contexts for actions and filters, which allow us to keep track of the source of every hook. - Migrate patches - Migrate commands - Migrate plugin detection - Migrate templates_root - Migrate config - Migrate template environment globals and filters - Migrate hooks to tasks - Generate hook documentation - Generate patch reference documentation - Add the concept of action priority Close #499.
2022-02-07 17:11:43 +00:00
============
Introduction
============
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
feat: plugin indexes We implement this TEP: https://discuss.openedx.org/t/tutor-enhancement-proposal-tep-plugin-indices/8182 With plugin indexes, tutor users can install and upgrade plugins directly from indexes: tutor plugins install ecommerce tutor plugins index add contrib tutor plugins install codejail tutor plugins upgrade all This change has been long in the coming \o/
2023-01-03 16:00:42 +00:00
Tutor comes with a plugin system that allows anyone to customise the deployment of an Open edX platform very easily. The vision behind this plugin system is that users should not have to fork the Tutor repository to customise their deployments. For instance, if you have created a new application that integrates with Open edX, you should not have to describe how to manually patch the platform settings, ``urls.py`` or ``*.env.yml`` files. Instead, you can create a "tutor-myapp" plugin for Tutor. This plugin will be in charge of making changes to the platform settings. Then, users will be able to use your application in three simple steps::
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
# 1) Install the plugin
pip install tutor-myapp
# 2) Enable the plugin
tutor plugins enable myapp
Add support for simple, yaml-based plugins Those plugins are stored as yaml files in ~/.local/share/tutor-plugins and follow the same specifications as entrypoint plugins.
2020-01-14 14:42:20 +00:00
# 3) Reconfigure and restart the platform
feat: deprecate "quickstart" and rename to "launch" `quickstart` is being renamed to `launch` and deprecated in favor of using `launch`. The `quickstart` function temporarily aliases to `launch`. Further mentions of `quickstart` have been changed to reference `launch` instead. We are indicating that this change is breaking 💥 to encourage people to migrate their scripts right away!
2022-09-30 10:00:24 +00:00
tutor local launch
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
feat: migrate to plugins.v1 with filters & actions This is a very large refactoring which aims at making Tutor both more extendable and more generic. Historically, the Tutor plugin system was designed as an ad-hoc solution to allow developers to modify their own Open edX platforms without having to fork Tutor. The plugin API was simple, but limited, because of its ad-hoc nature. As a consequence, there were many things that plugin developers could not do, such as extending different parts of the CLI or adding custom template filters. Here, we refactor the whole codebase to make use of a generic plugin system. This system was inspired by the Wordpress plugin API and the Open edX "hooks and filters" API. The various components are added to a small core thanks to a set of actions and filters. Actions are callback functions that can be triggered at different points of the application lifecycle. Filters are functions that modify some data. Both actions and filters are collectively named as "hooks". Hooks can optionally be created within a certain context, which makes it easier to keep track of which application created which callback. This new hooks system allows us to provide a Python API that developers can use to extend their applications. The API reference is added to the documentation, along with a new plugin development tutorial. The plugin v0 API remains supported for backward compatibility of existing plugins. Done: - Do not load commands from plugins which are not enabled. - Load enabled plugins once on start. - Implement contexts for actions and filters, which allow us to keep track of the source of every hook. - Migrate patches - Migrate commands - Migrate plugin detection - Migrate templates_root - Migrate config - Migrate template environment globals and filters - Migrate hooks to tasks - Generate hook documentation - Generate patch reference documentation - Add the concept of action priority Close #499.
2022-02-07 17:11:43 +00:00
For simple changes, it may be extremely easy to create a Tutor plugin: even non-technical users may get started with our :ref:`plugin_development_tutorial` tutorial. We also provide a list of :ref:`simple example plugins <plugins_examples>`.
Better documentation of simple yaml plugins
2020-05-18 09:24:09 +00:00
feat: refactor hooks API for simplification The hooks API had several issues which are summarized in this comment: https://github.com/openedx/wg-developer-experience/issues/125#issuecomment-1313553526 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 https://github.com/openedx/wg-developer-experience/issues/125
2023-01-06 18:02:17 +00:00
To learn about the different ways in which plugins can extend Tutor, check out the :ref:`hooks catalog <hooks_catalog>`.
feat: migrate to plugins.v1 with filters & actions This is a very large refactoring which aims at making Tutor both more extendable and more generic. Historically, the Tutor plugin system was designed as an ad-hoc solution to allow developers to modify their own Open edX platforms without having to fork Tutor. The plugin API was simple, but limited, because of its ad-hoc nature. As a consequence, there were many things that plugin developers could not do, such as extending different parts of the CLI or adding custom template filters. Here, we refactor the whole codebase to make use of a generic plugin system. This system was inspired by the Wordpress plugin API and the Open edX "hooks and filters" API. The various components are added to a small core thanks to a set of actions and filters. Actions are callback functions that can be triggered at different points of the application lifecycle. Filters are functions that modify some data. Both actions and filters are collectively named as "hooks". Hooks can optionally be created within a certain context, which makes it easier to keep track of which application created which callback. This new hooks system allows us to provide a Python API that developers can use to extend their applications. The API reference is added to the documentation, along with a new plugin development tutorial. The plugin v0 API remains supported for backward compatibility of existing plugins. Done: - Do not load commands from plugins which are not enabled. - Load enabled plugins once on start. - Implement contexts for actions and filters, which allow us to keep track of the source of every hook. - Migrate patches - Migrate commands - Migrate plugin detection - Migrate templates_root - Migrate config - Migrate template environment globals and filters - Migrate hooks to tasks - Generate hook documentation - Generate patch reference documentation - Add the concept of action priority Close #499.
2022-02-07 17:11:43 +00:00
Plugin commands cheatsheet
==========================
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
List installed plugins::
feat: upgrade to open-release/lilac.master One of the breaking changes of this release is the removal of the webui and android features; these are moved to dedicated plugins. This causes a breaking change: the renaming of the DOCKER_IMAGE_ANDROID config variable to ANDROID_DOCKER_IMAGE. See this TEP for reference: https://discuss.overhang.io/t/separate-webui-and-android-from-tutor-core-and-move-to-dedicated-plugins/1473
2021-04-13 20:14:43 +00:00
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
tutor plugins list
feat: upgrade to open-release/lilac.master One of the breaking changes of this release is the removal of the webui and android features; these are moved to dedicated plugins. This causes a breaking change: the renaming of the DOCKER_IMAGE_ANDROID config variable to ANDROID_DOCKER_IMAGE. See this TEP for reference: https://discuss.overhang.io/t/separate-webui-and-android-from-tutor-core-and-move-to-dedicated-plugins/1473
2021-04-13 20:14:43 +00:00
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
Enable/disable a plugin::
feat: upgrade to open-release/lilac.master One of the breaking changes of this release is the removal of the webui and android features; these are moved to dedicated plugins. This causes a breaking change: the renaming of the DOCKER_IMAGE_ANDROID config variable to ANDROID_DOCKER_IMAGE. See this TEP for reference: https://discuss.overhang.io/t/separate-webui-and-android-from-tutor-core-and-move-to-dedicated-plugins/1473
2021-04-13 20:14:43 +00:00
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
tutor plugins enable myplugin
tutor plugins disable myplugin
feat: upgrade to open-release/lilac.master One of the breaking changes of this release is the removal of the webui and android features; these are moved to dedicated plugins. This causes a breaking change: the renaming of the DOCKER_IMAGE_ANDROID config variable to ANDROID_DOCKER_IMAGE. See this TEP for reference: https://discuss.overhang.io/t/separate-webui-and-android-from-tutor-core-and-move-to-dedicated-plugins/1473
2021-04-13 20:14:43 +00:00
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
After enabling or disabling a plugin, the environment should be re-generated with::
feat: upgrade to open-release/lilac.master One of the breaking changes of this release is the removal of the webui and android features; these are moved to dedicated plugins. This causes a breaking change: the renaming of the DOCKER_IMAGE_ANDROID config variable to ANDROID_DOCKER_IMAGE. See this TEP for reference: https://discuss.overhang.io/t/separate-webui-and-android-from-tutor-core-and-move-to-dedicated-plugins/1473
2021-04-13 20:14:43 +00:00
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
tutor config save
feat: upgrade to open-release/lilac.master One of the breaking changes of this release is the removal of the webui and android features; these are moved to dedicated plugins. This causes a breaking change: the renaming of the DOCKER_IMAGE_ANDROID config variable to ANDROID_DOCKER_IMAGE. See this TEP for reference: https://discuss.overhang.io/t/separate-webui-and-android-from-tutor-core-and-move-to-dedicated-plugins/1473
2021-04-13 20:14:43 +00:00
feat: migrate to plugins.v1 with filters & actions This is a very large refactoring which aims at making Tutor both more extendable and more generic. Historically, the Tutor plugin system was designed as an ad-hoc solution to allow developers to modify their own Open edX platforms without having to fork Tutor. The plugin API was simple, but limited, because of its ad-hoc nature. As a consequence, there were many things that plugin developers could not do, such as extending different parts of the CLI or adding custom template filters. Here, we refactor the whole codebase to make use of a generic plugin system. This system was inspired by the Wordpress plugin API and the Open edX "hooks and filters" API. The various components are added to a small core thanks to a set of actions and filters. Actions are callback functions that can be triggered at different points of the application lifecycle. Filters are functions that modify some data. Both actions and filters are collectively named as "hooks". Hooks can optionally be created within a certain context, which makes it easier to keep track of which application created which callback. This new hooks system allows us to provide a Python API that developers can use to extend their applications. The API reference is added to the documentation, along with a new plugin development tutorial. The plugin v0 API remains supported for backward compatibility of existing plugins. Done: - Do not load commands from plugins which are not enabled. - Load enabled plugins once on start. - Implement contexts for actions and filters, which allow us to keep track of the source of every hook. - Migrate patches - Migrate commands - Migrate plugin detection - Migrate templates_root - Migrate config - Migrate template environment globals and filters - Migrate hooks to tasks - Generate hook documentation - Generate patch reference documentation - Add the concept of action priority Close #499.
2022-02-07 17:11:43 +00:00
The full plugins CLI is described in the :ref:`reference documentation <cli_plugins>`.
Fix erroneous docs on unsupported features.
2019-10-10 13:38:03 +00:00
.. _existing_plugins:
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
Existing plugins
feat: migrate to plugins.v1 with filters & actions This is a very large refactoring which aims at making Tutor both more extendable and more generic. Historically, the Tutor plugin system was designed as an ad-hoc solution to allow developers to modify their own Open edX platforms without having to fork Tutor. The plugin API was simple, but limited, because of its ad-hoc nature. As a consequence, there were many things that plugin developers could not do, such as extending different parts of the CLI or adding custom template filters. Here, we refactor the whole codebase to make use of a generic plugin system. This system was inspired by the Wordpress plugin API and the Open edX "hooks and filters" API. The various components are added to a small core thanks to a set of actions and filters. Actions are callback functions that can be triggered at different points of the application lifecycle. Filters are functions that modify some data. Both actions and filters are collectively named as "hooks". Hooks can optionally be created within a certain context, which makes it easier to keep track of which application created which callback. This new hooks system allows us to provide a Python API that developers can use to extend their applications. The API reference is added to the documentation, along with a new plugin development tutorial. The plugin v0 API remains supported for backward compatibility of existing plugins. Done: - Do not load commands from plugins which are not enabled. - Load enabled plugins once on start. - Implement contexts for actions and filters, which allow us to keep track of the source of every hook. - Migrate patches - Migrate commands - Migrate plugin detection - Migrate templates_root - Migrate config - Migrate template environment globals and filters - Migrate hooks to tasks - Generate hook documentation - Generate patch reference documentation - Add the concept of action priority Close #499.
2022-02-07 17:11:43 +00:00
================
Working Kubernetes quickstart The k8s quickstart command is now functional, with suppport for https, xqueue, notes and minio. There are still a few bugs to get rid of, though.
2019-06-06 19:58:21 +00:00
feat: plugin indexes We implement this TEP: https://discuss.openedx.org/t/tutor-enhancement-proposal-tep-plugin-indices/8182 With plugin indexes, tutor users can install and upgrade plugins directly from indexes: tutor plugins install ecommerce tutor plugins index add contrib tutor plugins install codejail tutor plugins upgrade all This change has been long in the coming \o/
2023-01-03 16:00:42 +00:00
Many plugins are available from plugin indexes. These indexes are lists of plugins, similar to the `pypi <https://pypi.org>`__ or `npm <npmjs.com/>`__ indexes. By default, Tutor comes with the "main" plugin index. You can check available plugins from this index by running::
tutor plugins update
tutor plugins search
More plugins can be downloaded from the "contrib" and "wizard" indexes::
tutor plugins index add contrib
tutor plugins index add wizard
tutor plugins search
The "main", "contrib" and "wizard" indexes include a curated list of plugins that are well maintained and introduce useful features to Open edX. These indexes are maintained by `Overhang.IO <https://overhang.io>`__. For more information about these indexes, refer to the official `overhangio/tpi <https://github.com/overhangio/tpi>`__ repository.
Thanks to these indexes, it is very easy to download and upgrade plugins. For instance, to install the `notes plugin <https://github.com/overhangio/tutor-notes/>`__::
tutor plugins install notes
Upgrade all your plugins with::
tutor plugins upgrade all
To list indexes that you are downloading plugins from, run::
tutor plugins index list
For more information about these indexes, check the `official Tutor plugin indexes (TPI) <https://github.com/overhangio/tpi/>`__ repository.
Copy Permalink