From 687066e598dbda6dc0c6fd509365f4c997286c67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9gis=20Behmo?= Date: Mon, 18 May 2020 11:24:09 +0200 Subject: [PATCH] Better documentation of simple yaml plugins --- docs/configuration.rst | 2 ++ docs/dev.rst | 24 ++++++------- docs/plugins.rst | 7 ++-- docs/plugins/examples.rst | 62 +++++++++++++++++++++++++++++++++ docs/plugins/gettingstarted.rst | 14 ++++---- 5 files changed, 89 insertions(+), 20 deletions(-) create mode 100644 docs/plugins/examples.rst diff --git a/docs/configuration.rst b/docs/configuration.rst index 8cfe697..f5ce84e 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -8,6 +8,8 @@ Tutor offers plenty of possibilities for platform customisation out of the box. a. Modifying the Tutor :ref:`configuration parameters `. b. Modifying the :ref:`Open edX docker image ` that runs the Open edX platform. +This section does not cover :ref:`plugin development `. For simple changes, such as modifying the ``*.env.json`` files or the edx-platform settings, *you should not fork edx-platform or tutor*! Instead, you should create a simple :ref:`plugin for Tutor `. + .. _configuration: Configuration diff --git a/docs/dev.rst b/docs/dev.rst index bec2b72..45dfb7c 100644 --- a/docs/dev.rst +++ b/docs/dev.rst @@ -74,18 +74,18 @@ Then, add the following content:: version: "3.7" services: - lms: - volumes: - - /path/to/edx-platform/:/openedx/edx-platform - cms: - volumes: - - /path/to/edx-platform/:/openedx/edx-platform - lms-worker: - volumes: - - /path/to/edx-platform/:/openedx/edx-platform - cms-worker: - volumes: - - /path/to/edx-platform/:/openedx/edx-platform + lms: + volumes: + - /path/to/edx-platform/:/openedx/edx-platform + cms: + volumes: + - /path/to/edx-platform/:/openedx/edx-platform + lms-worker: + volumes: + - /path/to/edx-platform/:/openedx/edx-platform + cms-worker: + volumes: + - /path/to/edx-platform/:/openedx/edx-platform This override file will be loaded when running any ``tutor dev ..`` command. The edx-platform repo mounted at the specified path will be automaticall mounted inside all LMS and CMS containers. With this file, you should no longer specify the ``-v`` option from the command line with the ``run`` or ``runserver`` commands. diff --git a/docs/plugins.rst b/docs/plugins.rst index 2a1ee5e..c6c55e1d 100644 --- a/docs/plugins.rst +++ b/docs/plugins.rst @@ -12,7 +12,9 @@ Tutor comes with a plugin system that allows anyone to customise the deployment # 3) Reconfigure and restart the platform tutor local quickstart -In the following we see how to use and create Tutor plugins. +For simple changes, it may be extremely easy to create a Tutor plugin: even non-technical users may get started with :ref:`simple yaml plugins `. + +In the following we learn how to use and create Tutor plugins. Commands -------- @@ -49,4 +51,5 @@ Plugin development :maxdepth: 2 plugins/api - plugins/gettingstarted \ No newline at end of file + plugins/gettingstarted + plugins/examples \ No newline at end of file diff --git a/docs/plugins/examples.rst b/docs/plugins/examples.rst new file mode 100644 index 0000000..347a54f --- /dev/null +++ b/docs/plugins/examples.rst @@ -0,0 +1,62 @@ +.. _plugins_examples: + +Examples of Tutor plugins +========================= + +The following are simple examples of :ref:`Tutor plugins ` that can be used to modify the behaviour of Open edX. + +Skip email validation for new users +----------------------------------- + +:: + + name: skipemailvalidation + version: 0.1.0 + patches: + common-env-features: | + "SKIP_EMAIL_VALIDATION": true + +Enable bulk enrollment view in the LMS +-------------------------------------- + +:: + + name: enablebulkenrollmentview + version: 0.1.0 + patches: + lms-env-features: | + "ENABLE_BULK_ENROLLMENT_VIEW": true + +Enable Google Analytics +----------------------- + +:: + + name: googleanalytics + version: 0.1.0 + patches: + openedx-common-settings: | + # googleanalytics special settings + GOOGLE_ANALYTICS_ACCOUNT = "UA-your-account" + GOOGLE_ANALYTICS_TRACKING_ID = "UA-your-tracking-id" + +Enable SAML authentication +-------------------------- + +:: + + name: saml + version: 0.1.0 + patches: + common-env-features: | + "ENABLE_THIRD_PARTY_AUTH" : true + + openedx-lms-common-settings: | + # saml special settings + THIRD_PARTY_AUTH_BACKENDS = "third_party_auth.saml.SAMLAuthBackend" + + openedx-auth: | + "SOCIAL_AUTH_SAML_SP_PRIVATE_KEY" : "yoursecretkey" + "SOCIAL_AUTH_SAML_SP_PUBLIC_CERT" : "yourpubliccert" + +Do not forget to replace "yoursecretkey" and "yourpubliccert" with your own values. diff --git a/docs/plugins/gettingstarted.rst b/docs/plugins/gettingstarted.rst index cdd21ac..6421a89 100644 --- a/docs/plugins/gettingstarted.rst +++ b/docs/plugins/gettingstarted.rst @@ -3,6 +3,8 @@ Getting started with plugin development Plugins can be created in two different ways: either as plain YAML files or installable Python packages. YAML files are great when you need to make minor changes to the default platform, such as modifying settings. For creating more complex applications, it is recommended to create python packages. +.. _plugins_yaml: + YAML file ~~~~~~~~~ @@ -20,22 +22,22 @@ Let's create a simple plugin that adds your own `Google Analytics