From 687066e598dbda6dc0c6fd509365f4c997286c67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9gis=20Behmo?= <regis@behmo.com>
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 <configuration>`.
 b. Modifying the :ref:`Open edX docker image <customise>` that runs the Open edX platform.
 
+This section does not cover :ref:`plugin development <plugins>`. 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 <plugins_yaml>`.
+
 .. _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..c6c55e1 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 <plugins_yaml>`.
+
+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 <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 <https://analy
 
 Then add the following content to the plugin file located at ``$(tutor plugins printroot)/myplugin.yml``::
 
-    name: myplugin
+    name: googleanalytics
     version: 0.1.0
     patches:
       openedx-common-settings: |
-        # myplugin special settings
+        # googleanalytics special settings
         GOOGLE_ANALYTICS_ACCOUNT = "UA-654321-1"
         GOOGLE_ANALYTICS_TRACKING_ID = "UA-654321-1"
 
 Of course, you should replace your Google Analytics tracking code with your own. You can verify that your plugin is correctly installed, but not enabled yet::
     
     $ tutor plugins list
-    myplugin@0.1.0 (disabled)
+    googleanalytics@0.1.0 (disabled)
     
 You can then enable your newly-created plugin::
     
-    tutor plugins enable myplugin
+    tutor plugins enable googleanalytics
 
 Update your environment to apply changes from your plugin::
     
@@ -43,7 +45,7 @@ Update your environment to apply changes from your plugin::
 
 You should be able to view your changes in every LMS and CMS settings file::
 
-    grep -r myplugin "$(tutor config printroot)/env/apps/openedx/settings/"
+    grep -r googleanalytics "$(tutor config printroot)/env/apps/openedx/settings/"
 
 Now just restart your platform to start sending tracking events to Google Analytics::
     
@@ -51,7 +53,7 @@ Now just restart your platform to start sending tracking events to Google Analyt
 
 That's it! And it's very easy to share your plugins. Just upload them to your Github repo and share the url with other users. They will be able to install your plugin by running::
     
-    tutor plugins install https://raw.githubusercontent.com/username/yourrepo/master/myplugin.yml
+    tutor plugins install https://raw.githubusercontent.com/username/yourrepo/master/googleanalytics.yml
 
 Python package
 ~~~~~~~~~~~~~~
-- 
GitLab