Better documentation of simple yaml plugins

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

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.
 

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
+   plugins/gettingstarted
+   plugins/examples

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.

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
 ~~~~~~~~~~~~~~