Dev Guide: Update sections on Extensions/XBlocks

Removed outdated information and added appropriate crosslinking of documents
openedx · Jul 2, 2024 · 33d07cc · 33d07cc
1 parent 91f2429
commit 33d07cc
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 90 deletions.
diff --git a/source/conf.py b/source/conf.py
@@ -79,6 +79,10 @@
         f"https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/{rtd_language}/{rtd_version}",
         None,
     ),
+    "openedx-building-and-running-a-course": (
+        f"https://edx.readthedocs.io/projects/open-edx-building-and-running-a-course/{rtd_language}/{rtd_version}",
+        None,
+    ),
     "edx-platform": (
         f"https://docs.openedx.org/projects/edx-platform/{rtd_language}/{rtd_version}",
         None,

diff --git a/source/developers/references/developer_guide/extending_platform/extending.rst b/source/developers/references/developer_guide/extending_platform/extending.rst
@@ -1,14 +1,15 @@
 
-.. _Options for Extending the edX Platform:
+.. _Options for Extending the Open edX Platform:
 
-######################################
-Options for Extending the edX Platform
-######################################
+###########################################
+Options for Extending the Open edX Platform
+###########################################
 
 There are several options for extending the Open edX Platform to provide useful
 and innovative educational content in your courses.
 
-This section of the developers' documentation lists and explains the different ways to extend the platform, starting with the following table.
+This section of the developers' documentation lists and explains the different
+ways to extend the platform, starting with the following table.
 
 .. |br| raw:: html
 
@@ -48,19 +49,19 @@ This section of the developers' documentation lists and explains the different w
      - Yes
    * - Self-hosting Needed
      - No
-     - Yes
+     - Yes, if building a new LTI unit. Many LTI tools are hosted elsewhere.
      - Yes
      - No
      - No
-   * - Need edX Involvement
+   * - Requires Sysadmin Installation on Your Open edX Instance
      - No
      - No
      - Yes
      - Yes
      - Yes
    * - Clean UI Integration
      - Yes
-     - No (see LTI)
+     - No (see :doc:`openedx-building-and-running-a-course:exercises_tools/lti_component`)
      - Yes
      - Yes
      - Yes
@@ -71,13 +72,13 @@ This section of the developers' documentation lists and explains the different w
      - Yes
      - Yes
    * - Server Side Grading
-     - Possibly (See JavaScript)
+     - Possibly (See :doc:`openedx-building-and-running-a-course:exercises_tools/custom_javascript`)
      - Yes
      - Yes
      - Yes
      - Yes
    * - Usage Data
-     - No (See JavaScript)
+     - No (See :doc:`openedx-building-and-running-a-course:exercises_tools/custom_javascript`)
      - No
      - Limited
      - Yes
@@ -88,9 +89,9 @@ This section of the developers' documentation lists and explains the different w
      - No
      - Yes
      - No
-   * - Privacy Loss Compared to Hosting Open edX
+   * - Learner Data Privacy Loss?
      - No
-     - Possibly
-     - Possibly
+     - Possibly (Depends on LTI tool used)
+     - Possibly (Depends on external grader implementation)
      - No
      - No
diff --git a/source/developers/references/developer_guide/extending_platform/xblocks.rst b/source/developers/references/developer_guide/extending_platform/xblocks.rst
@@ -1,34 +1,30 @@
 Integrating XBlocks with edx-platform
 #####################################
 
-The edX LMS and Studio have several features that are extensions of the core
-XBlock libraries (https://xblock.readthedocs.io). These features are listed
-below.
+The Open edX LMS and Studio have several features that are extensions of the core
+XBlock libraries (:doc:`xblock:xblock-tutorial/index` and :doc:`xblock:index`).
+These features are listed below.
 
-* `LMS`_
-* `Studio`_
-* `Testing`_
-* `Deploying your XBlock`_
+.. contents::
+   :local:
+   :depth: 1
 
-You can also render an individual XBlock in HTML with the :ref:`XBlock
-URL<XBlock URL Dev>`.
 
-***
 LMS
 ***
 
-================
+
 Runtime Features
 ================
 
 These are properties and methods available on ``self.runtime`` when a view or
 handler is executed by the LMS.
 
-* anonymous_student_id: An identifier unique to the student in the particular
+* ``anonymous_student_id``: An identifier unique to the student in the particular
   course that the block is being executed in. The same student in two different
   courses will have two different ids.
 
-* publish(block, event_type, event): Emit events to the surrounding system.
+* ``publish(block, event_type, event)``: Emit events to the surrounding system.
   Events are dictionaries that can contain arbitrary data. XBlocks can publish
   events by calling ``self.runtime.publish(self, event_type, event)``. The
   ``event_type`` parameter enables downstream processing of the event since it
@@ -39,30 +35,31 @@ handler is executed by the LMS.
   application. Ideally interesting state of the XBlock could be reconstructed
   at any point in history through careful analysis of the event stream.
 
-..  TODO: Link to the authoritative list of event types.
+See more about event types in :doc:`xblock:xblock-tutorial/concepts/events`.
 
 In the future, these are likely to become more formal XBlock services (one
 related to users, and the other to event publishing).
 
-==============
 Class Features
 ==============
 
 These are class attributes or functions that can be provided by an XBlock to
 customize behavior in the LMS.
 
-* student_view (XBlock view): This is the view that will be rendered to display
+* ``student_view`` (XBlock view): This is the view that will be rendered to display
   the XBlock in the LMS. It will also be used to render the block in "preview"
   mode in Studio, unless the XBlock also implements author_view.
-* has_score (class property): True if this block should appear in the LMS
+* ``has_score`` (class property): True if this block should appear in the LMS
   progress page.
-* get_progress (method): See documentation in
-  x_module.py:XModuleMixin.get_progress.
-* icon_class (class property): This can be one of (``other``, ``video``, or
-  ``problem``), and determines which icon appears in edx sequence headers.
+* ``get_progress`` (method): See documentation in
+  `x_module.py:XModuleMixin.get_progress
+  <https://github.com/openedx/edx-platform/blob/master/xmodule/x_module.py#L565-L573>`_
+  and also see documentation on the `Progress class <https://github.com/openedx/edx-platform/blob/master/xmodule/progress.py#L12>`_.
+* ``icon_class`` (class property): This can be one of (``other``, ``video``, or
+  ``problem``), and determines which icon appears in Open edX sequence headers.
   There is currently no way to provide a different icon.
 
-=======
+
 Grading
 =======
 
@@ -82,35 +79,33 @@ The grade event represents a grade of ``value/max_value`` for the current user.
 The ``user_id`` field is optional, the currently logged in user's ID will be
 used if it is omitted.
 
-============
 Restrictions
 ============
 
 A block cannot modify the value of any field with a scope where the ``user``
 property is ``UserScope.NONE``.
 
-******
+
 Studio
 ******
 
-==============
+
 Class Features
 ==============
 
-* studio_view (XBlock.view): The view used to render an editor in Studio. The
+* ``studio_view`` (XBlock.view): The view used to render an editor in Studio. The
   editor rendering can be completely different from the LMS student_view, and
   it is only shown when the author selects "Edit".
 
-* author_view (XBlock.view): An optional view of the XBlock similar to
+* ``author_view`` (XBlock.view): An optional view of the XBlock similar to
   student_view, but with possible inline editing capabilities. This view
-  differs from studio_view in that it should be as similar to student_view as
+  differs from ``studio_view`` in that it should be as similar to ``student_view`` as
   possible. When previewing XBlocks within Studio, Studio will prefer
-  author_view to student_view.
+  ``author_view`` to ``student_view``.
 
-* non_editable_metadata_fields (property): A list of ``xblock.fields.Field``
+* ``non_editable_metadata_fields`` (property): A list of ``xblock.fields.Field``
   objects that should not be displayed in the default editing view for Studio.
 
-============
 Restrictions
 ============
 
@@ -119,35 +114,10 @@ property is not ``UserScope.NONE``.
 
 
 Testing
--------
-
-These instructions are temporary. Once XBlocks are fully supported by
-edx-platform (both the LMS and Studio), installation and testing will be much
-more straightforward.
-
-To enable an XBlock for testing in your devstack
-(https://github.com/openedx/configuration/wiki/edX-Developer-Stack), follow these
-steps.
-
-#.  Install your block.
-
-    .. code-block:: bash
-
-        vagrant ssh
-        vagrant@precise64:~$ sudo -u edxapp /edx/bin/pip.edxapp install /path/to/your/block
-
-#.  Enable the block.
-
-    #.  In ``edx-platform/lms/envs/common.py``, uncomment::
-
-        # from xmodule.x_module import prefer_xmodules
-        # XBLOCK_SELECT_FUNCTION = prefer_xmodules
-
-    #.  In ``edx-platform/cms/envs/common.py``, uncomment::
-
-        # from xmodule.x_module import prefer_xmodules
-        # XBLOCK_SELECT_FUNCTION = prefer_xmodules
+*******
 
+#. To enable an XBlock for testing in Tutor, follow the instructions to `install
+   an XBlock in development mode <https://docs.tutor.overhang.io/dev.html#xblock-and-edx-platform-plugin-development>`_.
 
 #.  Add the block to your courses' advanced settings in Studio.
 
@@ -164,34 +134,30 @@ steps.
 Note the name ``your-block`` used in Studio must exactly match the key you used
 to add your block to your ``setup.py`` ``entry_points`` list. (If you are still
 discovering XBlocks and simply used the ``workbench-make-new.py`` script as
-described in the `xblocktutorial:Open edX XBlock Tutorial`, look in the
+described in the :doc:`xblock:xblock-tutorial/index`, look in the
 ``setup.py`` file that was created.)
 
-*********************
+
 Deploying Your XBlock
 *********************
 
-To deploy your block to your own hosted version of edx-platform, you need to
-install it into the virtualenv that the platform is running out of, and add to
-the list of ``ADVANCED_COMPONENT_TYPES`` in
-``edx-platform/cms/djangoapps/contentstore/views/component.py``.
+To deploy your block to your own hosted version of edx-platform, follow the
+instructions to `deploy XBlocks on Tutor <https://docs.tutor.overhang.io/configuration.html#installing-extra-xblocks-and-requirements>`_.
 
 
-.. _XBlock URL Dev:
 
-*************************************
 Rendering XBlocks with the XBlock URL
 *************************************
 
 The XBlock URL supports HTML rendering of an individual XBlock without the user
 interface of the LMS.
 
 To use the XBlock URL and return the HTML rendering of an individual XBlock,
-you use the following URL path for an XBlock on an edX site.
+you use the following URL path for an XBlock on an Open edX site.
 
 ``https://{host}/xblock/{usage_id}``
 
-========================
+
 Finding the ``usage_id``
 ========================
 
@@ -200,16 +166,16 @@ other course content component, or for sequential or vertical course container
 component. There are several ways to find the ``usage_id`` for an XBlock in the
 LMS, including viewing either the staff debug info or the page source. For more
 information, see
-`opencoursestaff:Finding the Usage ID for Course Content`.
+:doc:`openedx-building-and-running-a-course:course_features/lti/lti_address_content`.
+
 
-===================
 Example XBlock URLs
 ===================
 
 For example, a video component in the "Creating Video for the edX Platform"
-course on the edx.org site has the following URL.
+course on the edx.org site has the following URL:
 
-``https://courses.edx.org/courses/course-v1:edX+VideoX+1T2016/courseware/ccc7c32c65d342618ac76409254ac238/1a52e689bcec4a9eb9b7da0bf16f682d/``
+   https://courses.edx.org/courses/course-v1:edX+VideoX+1T2016/courseware/ccc7c32c65d342618ac76409254ac238/1a52e689bcec4a9eb9b7da0bf16f682d/
 
 This video component appears as follows in the LMS.
 
@@ -218,9 +184,9 @@ This video component appears as follows in the LMS.
         navigational options to reach all other course content.
 
 To construct the XBlock URL for the same video component, you obtain its
-``usage_id`` and then use the following URL format.
+``usage_id`` and then use the following URL format:
 
-``https://courses.edx.org/xblock/block-v1:edX+VideoX+1T2016+type@video+block@47faf3a03c4f4023b187528c25932e0a``
+   https://courses.edx.org/xblock/block-v1:edX+VideoX+1T2016+type@video+block@47faf3a03c4f4023b187528c25932e0a
 
 When you use this URL, the video component appears in your browser as follows.
 
@@ -229,6 +195,6 @@ When you use this URL, the video component appears in your browser as follows.
         course content.
 
 For courses created prior to October 2014, the ``usage_id`` begins with
-``i4x://``, as in the following example.
+``i4x://``, as in the following example:
 
-``https://courses.edx.org/xblock/i4x://edX/DemoX.1/problem/47bf6dbce8374b789e3ebdefd74db332``
+   https://courses.edx.org/xblock/i4x://edX/DemoX.1/problem/47bf6dbce8374b789e3ebdefd74db332