feat: add explanation of patches

overhangio · Jun 9, 2023 · a5d8173 · a5d8173
1 parent fb15f21
commit a5d8173
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 1 deletion.
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -6,6 +6,6 @@ Reference
 
    api/hooks/index
    api/hooks/catalog
-   patches
+   patches/index
    cli/index
    indexes
diff --git a/docs/reference/patches.rst → docs/reference/patches/catalog.rst b/docs/reference/patches.rst → docs/reference/patches/catalog.rst
diff --git a/docs/reference/patches/index.rst b/docs/reference/patches/index.rst
@@ -0,0 +1,27 @@
+==========
+Patches
+==========
+
+Patches are mechanisms that Tutor offers to plugin developers to modify the templates rendered to alter our environment. In many places, the Tutor templates include calls to ``{{ patch("patchname") }}``. Plugins can add content in these places with ``hooks.Filters.ENV_PATCHES.add_item``.
+
+Example::
+
+    from tutor import hooks
+
+    hooks.Filters.ENV_PATCHES.add_item(
+        (
+            "openedx-lms-common-settings",
+            "FEATURES['ALLOW_PUBLIC_ACCOUNT_CREATION'] = False"
+        )
+    )
+
+This will add ``FEATURES['ALLOW_PUBLIC_ACCOUNT_CREATION'] = False`` to the lms common settings with a Python Tutor plugin.
+
+.. note:: If you want a Package Tutor plugin, we recommend you to use the `overhangio/cookiecutter-tutor-plugin <https://github.com/overhangio/cookiecutter-tutor-plugin>`_ and add in the patches directory a file with the name of the patch, and inside the file add the content you want to add to the templates that use that patch.
+
+You can find a list of all patches used across Tutor here:
+
+.. toctree::
+   :maxdepth: 1
+
+   catalog