From 66dfeec9240e9b34c8638dd916dfc1bf183f0807 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 19 Nov 2023 20:58:29 -0500 Subject: [PATCH] docs: Match docs on myxblock.py with the actual code in the xblock sdk --- .../customize/custom-python.rst | 44 +++++++++---------- docs/xblock-tutorial/edx_platform/edx_lms.rst | 12 ++--- .../edx_platform/edx_studio.rst | 12 ++--- .../reusable/code_myxblock_python.rst | 11 +++-- 4 files changed, 41 insertions(+), 38 deletions(-) diff --git a/docs/xblock-tutorial/customize/custom-python.rst b/docs/xblock-tutorial/customize/custom-python.rst index cd06c8e74..2f8bff396 100644 --- a/docs/xblock-tutorial/customize/custom-python.rst +++ b/docs/xblock-tutorial/customize/custom-python.rst @@ -1,8 +1,8 @@ .. _Customize myxblock.py: -####################### +##################### Customize myxblock.py -####################### +##################### This section describes how to modify the Python file of the XBlock you created, ``myxblock.py``, to provide the functionality in the Thumbs XBlock example in @@ -16,9 +16,9 @@ scenarios. :local: :depth: 1 -******************************* +****************************** The Default XBlock Python File -******************************* +****************************** When you :ref:`create a new XBlock `, the default Python file is created automatically, with skeletal functionality defined. In @@ -27,18 +27,18 @@ the ``xblock_development/myxblock/myxblock/`` directory, see the file .. include:: ../reusable/code_myxblock_python.rst -******************** +************ Add Comments -******************** +************ As a best practice and because XBlocks can be shared, you should add comments to the ``myxblock.py`` file. Replace the "TO DO" indicators with a description of what the XBlock does and any details future developers or users would want to know. -******************** +***************** Add XBlock Fields -******************** +***************** You determine the data your XBlock stores through :ref:`fields `. Fields store user and XBlock state as JSON data. @@ -60,9 +60,9 @@ Review the :ref:`XBlock Fields` section, then add the required fields to ``myxblock.py``. You can remove the ``count`` field, which was defined automatically when you created the XBlock. -======================================= +====================================== Check Fields Against the Thumbs XBlock -======================================= +====================================== After you have defined the fields, check your work against the fields in the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/thumbs.py``. @@ -81,17 +81,17 @@ Note the following details. * ``voted`` has the scope ``Scope.user_state``. This indicates that the data in this field applies to the XBlock and to the specific user. -************************** +*********************** Define the Student View -************************** +*********************** The XBlock Python file must contain one or more :ref:`view methods`. -To run the XBlock in the edX Platform Learning Management System, there must be +To run the XBlock in the Open edX Platform Learning Management System, there must be a method named ``student_view``. If you intend the XBlock to run in a different :ref:`runtime application `, you might need to define a -different name. For more information, see :ref:`EdX Learning Management +different name. For more information, see :ref:`Open edX Learning Management System as an XBlock Runtime`. In ``myxblock.py``, examine the ``student_view`` method that was defined @@ -111,7 +111,7 @@ Note the following details about student view. frag = Fragment(unicode(html_str).format(self=self)) * The JavaScript and CSS files are added to the fragment with the - ``add_javascript()`` and ``add_css`` methods. + ``add_javascript()`` and ``add_css()`` methods. * The JavaScript in the fragment must be initialized using the name of the XBlock class. The name also maps to the function that initializes the XBlock @@ -127,9 +127,9 @@ Check the student view in ``myxblock.py`` against the student view in CSS, and JavaScript files added to the fragment. As the file names are correct for MyXBlock, you do not need to edit the student view at all. -************************** +*********************** Define the Vote Handler -************************** +*********************** :ref:`Handlers ` process input events from the XBlock JavaScript code. You use handlers to add interactivity to your block. In @@ -150,9 +150,9 @@ You can use any name for the vote handler, and you will use the same name in the JavaScript code to connect browser events to the vote handler running in the server. To match the Thumbs XBlock, use the name ``vote``. -============================================ +=========================================== Check the Handler Against the Thumbs XBlock -============================================ +=========================================== After you have defined the vote handler, check your work against the handler in the Thumbs XBlock. @@ -162,11 +162,11 @@ in the Thumbs XBlock. If necessary, make corrections to the handler in your XBlock so that it matches the handler in the Thumbs XBlock. -********************************** +********* Next Step -********************************** +********* -After you complete your customizations to the Python file, you continue on and +After you complete your customizations to the Python file, you can continue on and :ref:`customize the XBlock HTML file`. .. include:: ../../links.rst diff --git a/docs/xblock-tutorial/edx_platform/edx_lms.rst b/docs/xblock-tutorial/edx_platform/edx_lms.rst index fa5928c23..8a33ddb3c 100644 --- a/docs/xblock-tutorial/edx_platform/edx_lms.rst +++ b/docs/xblock-tutorial/edx_platform/edx_lms.rst @@ -1,10 +1,10 @@ -.. _EdX Learning Management System as an XBlock Runtime: +.. _Open edX Learning Management System as an XBlock Runtime: -#################################################### -EdX Learning Management System as an XBlock Runtime -#################################################### +######################################################## +Open edX Learning Management System as an XBlock Runtime +######################################################## -The edX Learning Management System (LMS) is the application in the edX Platform +The Open edX Learning Management System (LMS) is the application in the Open edX Platform that learners use to view and interact with courseware. Because it presents XBlocks to learners and records their interactions, the LMS @@ -28,7 +28,7 @@ The LMS requires XBlocks to have the following properties. In addition, the ``student_view`` method is used to render the XBlock in the Studio preview mode, unless the XBlock also has an ``author_view`` method. - For more information, see :ref:`EdX Studio as an XBlock Runtime`. + For more information, see :ref:`Open edX Studio as an XBlock Runtime`. * A class property named ``has_score`` with a value of ``True`` if the XBlock is to be graded. diff --git a/docs/xblock-tutorial/edx_platform/edx_studio.rst b/docs/xblock-tutorial/edx_platform/edx_studio.rst index cd1770e76..dedad42e8 100644 --- a/docs/xblock-tutorial/edx_platform/edx_studio.rst +++ b/docs/xblock-tutorial/edx_platform/edx_studio.rst @@ -1,10 +1,10 @@ -.. _EdX Studio as an XBlock Runtime: +.. _Open edX Studio as an XBlock Runtime: -############################### -EdX Studio as an XBlock Runtime -############################### +#################################### +Open edX Studio as an XBlock Runtime +#################################### -EdX Studio is the application in the edX Platform that instructors use to build +Open edX Studio is the application in the Open edX Platform that instructors use to build courseware. Because instructors use Studio to add and configure XBlocks, Studio is @@ -31,7 +31,7 @@ Studio requires XBlocks to have the following properties. ``student_view``, but may contain inline editing capabilities. If you do not define an ``author_view``, the preview mode uses the - ``student_view``. For more information, see :ref:`EdX Learning Management + ``student_view``. For more information, see :ref:`Open edX Learning Management System as an XBlock Runtime`. * A class property named ``non_editable_metadata_fields``. This variable diff --git a/docs/xblock-tutorial/reusable/code_myxblock_python.rst b/docs/xblock-tutorial/reusable/code_myxblock_python.rst index 867aa263a..61553efae 100644 --- a/docs/xblock-tutorial/reusable/code_myxblock_python.rst +++ b/docs/xblock-tutorial/reusable/code_myxblock_python.rst @@ -4,9 +4,9 @@ import pkg_resources + from web_fragments.fragment import Fragment from xblock.core import XBlock - from xblock.fields import Scope, Integer - from xblock.fragment import Fragment + from xblock.fields import Integer, Scope class MyXBlock(XBlock): @@ -61,11 +61,14 @@ """A canned scenario for display in the workbench.""" return [ ("MyXBlock", - """ + """ + """), + ("Multiple MyXBlock", + """ - """), + """), ]