Merge pull request #686 from openedx/sarina/move-xblock-tutorial

Move xblock tutorial docs to this repo

docs/conf.py

@@ -264,6 +264,12 @@
 
 exclude_patterns = ['api/*', 'links.rst']
 
+# Intersphinx Extension Configuration
+
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
+    "docs-openedx-org": (
+        f"https://docs.openedx.org/en/latest",
+        None,
+    ),
 }

docs/index.rst

@@ -1,14 +1,14 @@
-.. _EdX XBlock API Guide:
+.. _Open edX XBlock API Guide:
 
-#####################
-EdX XBlock API Guide
-#####################
+#########################
+Open edX XBlock API Guide
+#########################
 
 
 This document provides reference information on the XBlock API. You use this
 API to build XBlocks.
 
-EdX also provides the `EdX XBlock Tutorial`_, which describes XBlock concepts
+This document also contains the Open edX XBlock Tutorial, which describes XBlock concepts
 in depth and guides developers through the process of creating an XBlock.
 
 .. toctree::
@@ -22,6 +22,5 @@ in depth and guides developers through the process of creating an XBlock.
     fragment
     plugins
     exceptions
+    xblock-tutorial/index
     xblock-utils/index
-
-.. _EdX XBlock Tutorial: http://edx.readthedocs.org/projects/xblock-tutorial/en/latest/index.html

docs/introduction.rst

@@ -1,8 +1,16 @@
-.. _Introduction to XBlocks:
-
-#############################
+#######################
 Introduction to XBlocks
-#############################
+#######################
+
+This section introduces XBlocks.
+
+.. contents::
+ :local:
+ :depth: 1
+
+********
+Overview
+********
 
 As a developer, you build XBlocks that course teams use to create independent
 course components that work seamlessly with other components in an online
@@ -14,17 +22,18 @@ can build XBlocks to represent larger structures such as lessons, sections, and
 entire courses.
 
 A primary advantage to XBlocks is that they are sharable. The code you write
-can be deployed in any instance of the edX Platform or other XBlock runtime
+can be deployed in any instance of the Open edX Platform or other XBlock runtime
 application, then used by any course team using that system.
 
-By combining XBlocks from a wide variety of sources, from text and video, to
-multiple choice and numerical questions, to sophisticated collaborative and
-interactive learning laboratories, course teams can create rich and engaging
-courseware.
+In educational applications, XBlocks can be used to represent individual
+problems, web-formatted text and videos, interactive simulations and labs, or
+collaborative learning experiences. Furthermore, XBlocks are composable,
+allowing an XBlock developer to control the display of other XBlocks to compose
+lessons, sections, and entire courses.
 
-*****************************************
+****************************************
 XBlock Independence and Interoperability
-*****************************************
+****************************************
 
 You must design your XBlock to meet two goals.
 
@@ -34,9 +43,9 @@ You must design your XBlock to meet two goals.
 * The XBlock must work together with other XBlocks. Course teams must be
   able to combine different XBlocks in flexible ways.
 
-*****************************************
+************************************
 XBlocks Compared to Web Applications
-*****************************************
+************************************
 
 XBlocks are like miniature web applications: they maintain state in a storage
 layer, render themselves through views, and process user actions through

docs/links.rst

@@ -0,0 +1,64 @@
+.. Include this file in any file that includes a non-doc link.
+
+.. _thumbs.py: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/thumbs.py
+
+.. _thumbs.js: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/static/js/src/thumbs.js
+
+.. _Thumbs XBlock:  https://github.com/openedx/xblock-sdk/tree/master/sample_xblocks/thumbs
+
+.. _1.js: https://github.com/openedx/xblock-sdk/blob/master/workbench/static/workbench/js/runtime/1.js
+
+.. _devstack: https://github.com/openedx/devstack
+
+.. _edx.org: http://edx.org
+
+.. _edx-platform: https://github.com/openedx/edx-platform
+
+.. _RST: http://docutils.sourceforge.net/rst.html
+
+.. _Sphinx: http://sphinx-doc.org/
+
+.. _Download Python: https://www.python.org/downloads/release/python-386/
+
+.. _GitHub Help: https://help.github.com/articles/set-up-git
+.. _Git: https://help.github.com/articles/set-up-git
+
+.. _VirtualEnv: http://www.virtualenv.org/en/latest/
+
+.. _Virtual Environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/
+
+.. _VirtualEnv Installation: https://virtualenv.pypa.io/en/latest/installation.html
+
+.. _VirtualEnvWrapper: http://virtualenvwrapper.readthedocs.io/en/latest
+
+.. _XBlock SDK: https://github.com/openedx/xblock-sdk
+
+.. _PyEnv: https://github.com/yyuu/pyenv
+
+.. _Problem XBlock: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/problem.py
+
+.. _Content XBlocks: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/content.py
+
+.. _Slider XBlock: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/slider.py
+
+.. _Structure XBlocks: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/structure.py
+
+.. _View Counter XBlock: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/view_counter.py
+
+.. _requirements/edx/github.txt: https://github.com/openedx/edx-platform/blob/master/requirements/edx/github.txt
+
+.. _thumbs.html: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/static/html/thumbs.html
+
+.. _thumbs.css: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/thumbs/static/css/thumbs.css
+
+.. _Google Drive file tool: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/google_docs.html
+
+.. _Open Response Assessments: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/open_response_assessments/OpenResponseAssessments.html
+
+.. _Google calendar tool: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/exercises_tools/google_calendar.html
+
+.. _Finding the Usage ID for Course Content: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/course_features/lti/lti_address_content.html#finding-the-usage-id-for-course-content
+
+.. _Installing, Configuring, and Running the Open edX Platform: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/index.html
+
+.. _Developing Course Components: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/course_components.html

docs/xblock-tutorial/anatomy/html.rst

@@ -0,0 +1,29 @@
+.. _The XBlock HTML File:
+
+####################
+The XBlock HTML File
+####################
+
+This section of the tutorial walks through the HTML file, `thumbs.html`_,  that
+is part of the Thumbs XBlock in the XBlock SDK.
+
+If you completed the steps in :ref:`Build an XBlock Quick Start`, you can find
+this file locally at ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/html/thumbs.html``.
+
+In the XBlock HTML file, you define the HTML content that is added to a
+:ref:`fragment <XBlock Fragments>`. The HTML content can reference the XBlock
+:ref:`fields <XBlock Fields>`. The fragment is returned by the :ref:`view
+method <View Methods>`, to be displayed by the :ref:`runtime <XBlock
+Runtimes>` application.
+
+.. include:: ../reusable/code_thumbs_html.rst
+
+Note the following details about the HTML file.
+
+* The ``class`` values reference styles in the ``thumbs.css`` file. For more
+  information, see :ref:`The XBlock Stylesheets`.
+
+* The values ``self.upvotes`` and ``self.downvotes`` reference the fields in
+  the XBlock Python class.
+
+.. include:: ../../links.rst

docs/xblock-tutorial/anatomy/index.rst

@@ -0,0 +1,24 @@
+.. _Anatomy of an XBlock:
+
+####################
+Anatomy of an XBlock
+####################
+
+This part of the tutorial explains the XBlock skeleton, and uses examples from
+the `Thumbs XBlock`_ that is installed with the XBlock SDK.
+
+The Thumbs XBlock enables learners to vote up or down. The Thumbs XBlock keeps
+track of vote totals.
+
+For information about making the XBlock that you created function like the
+example Thumbs XBlock, see :ref:`Customize Your XBlock`.
+
+.. toctree::
+   :maxdepth: 2
+
+   python
+   html
+   javascript
+   stylesheets
+
+.. include:: ../../links.rst

docs/xblock-tutorial/anatomy/javascript.rst

@@ -0,0 +1,48 @@
+.. _The XBlock JavaScript File:
+
+##########################
+The XBlock JavaScript File
+##########################
+
+This section of the tutorial walks through the JavaScript file, `thumbs.js`_,
+that is part of the Thumbs XBlock in the XBlock SDK.
+
+If you completed the steps in :ref:`Build an XBlock Quick Start`, you can find
+this file locally at ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/source/thumbs.js``.
+
+In the XBlock JavaScript file, you define code that manages user interaction
+with the XBlock. The code is added to a :ref:`fragment <XBlock
+Fragments>`. 
+
+The XBlock’s JavaScript uses the runtime handler, and can use the ``children``
+and ``childMap`` functions as needed.
+
+The JavaScript references the XBlock :ref:`fields <XBlock Fields>`
+and :ref:`methods <XBlock Methods>`. The fragment is returned by the :ref:`view
+method <View Methods>`, to be displayed by the :ref:`runtime <XBlock Runtimes>`
+application.
+
+.. include:: ../reusable/code_thumbs_javascript.rst
+
+Note the following details about the JavaScript file.
+
+* The function ``ThumbsBlock`` initializes the XBlock. A JavaScript function to
+  initialize the XBlock is required.
+
+* The ``ThumbsBlock`` function maps to the contstructor in the :ref:`XBlock
+  Python file <The XBlock Python File>` and provides access to its methods and
+  fields.
+
+* The ``ThumbsBlock`` function uses the runtime handler.
+
+  .. code-block:: javascript
+
+    var handlerUrl = runtime.handlerUrl(element, 'vote');
+  
+* The ``ThumbsBlock`` function includes the ``Post`` commands to increase the up
+  and down votes in the XBlock.
+
+The XBlock JavaScript code can also use the ``children`` and ``childMap``
+functions as needed. For more information, see :ref:`XBlock Children`.
+
+.. include:: ../../links.rst

docs/xblock-tutorial/anatomy/python.rst

@@ -0,0 +1,96 @@
+.. _The XBlock Python File:
+
+#######################
+The XBlock Python File
+#######################
+
+This section of the tutorial walks through the Python file, `thumbs.py`_, for
+the Thumbs XBlock example in the XBlock SDK.
+
+If you completed the steps in :ref:`Build an XBlock Quick Start`, you can find
+this file locally at ``xblock_development/xblock-sdk/sample_xblocks/thumbs/thumbs.py``.
+
+In the XBlock Python file, you define :ref:`fields <XBlock Fields>`,
+:ref:`views <View Methods>`, :ref:`handlers <Handler Methods>`, and workbench
+scenarios.
+
+.. contents::
+ :local:
+ :depth: 1 
+
+********************
+Thumb XBlock Fields
+********************
+
+The ``thumbs.py`` file defines the following fields for the XBlock in the
+``ThumbsBlockBase`` class.
+
+.. include:: ../reusable/code_thumbs_fields.rst
+
+Note the following details about the fields in the Thumbs XBlock.
+
+* ``upvotes`` and ``downvotes`` store the cumulative up and down votes of
+  users.
+
+  These fields have the scope ``Scope.user_state_summary``. This indicates that
+  the data in these fields are specific to the XBlock and the same for all
+  users.
+
+* ``voted`` stores whether the user has voted. This field has the scope
+  ``Scope.user_state``. This indicates that the data in this field applies to
+  the XBlock and to the specific user.
+
+For more information, see :ref:`XBlock Fields`.  
+
+**************************
+Thumb XBlock Student View
+**************************
+
+The ``thumbs.py`` file defines the student view for the XBlock in the
+``ThumbsBlockBase`` class. 
+
+.. include:: ../reusable/code_thumbs_student_view.rst
+
+The student view composes and returns the fragment from static HTML,
+JavaScript, and CSS files. A web page displays the fragment to learners.
+
+Note the following details about student view.
+
+* The static HTML content is added when the fragment is initialized.
+
+  .. code-block:: python
+
+     html_str = pkg_resources.resource_string(__name__, "static/html/thumbs.html")
+     frag = Fragment(unicode(html_str).format(self=self))
+
+*  The JavaScript and CSS file contents are added to the fragment with the
+   ``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 in the :ref:`JavaScript file <The XBlock JavaScript File>`.
+
+  .. code-block:: python
+
+     frag.initialize_js('ThumbsBlock')
+
+For more information, see :ref:`View Methods`.
+
+**************************
+Thumb XBlock Vote Handler
+**************************
+
+The ``thumbs.py`` file defines a handler that adds a user's vote to the XBlock.
+
+.. include:: ../reusable/code_thumbs_vote_handler.rst
+
+Note the following details about the vote handler.
+
+* The ``upvotes`` or ``downvotes`` fields are updated based on the user's vote.
+
+* The ``voted`` field is set to ``True`` for the user.
+
+* The updated ``upvotes`` and ``downvotes`` fields are returned.
+
+For more information, see :ref:`Handler Methods`.
+
+.. include:: ../../links.rst

docs/xblock-tutorial/anatomy/stylesheets.rst

@@ -0,0 +1,22 @@
+.. _The XBlock Stylesheets:
+
+######################
+The XBlock Stylesheets
+######################
+
+This section of the tutorial walks through the CSS file, `thumbs.css`_,  that
+is part of the Thumbs XBlock in the XBlock SDK.
+
+If you completed the steps in :ref:`Build an XBlock Quick Start`, you can find
+this file locally at ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/css/thumbs.css``.
+
+In the XBlock CSS file, you define the styles that are added to the
+fragment that is returned by the view method to be displayed by the runtime
+application.
+
+.. include:: ../reusable/code_thumbs_css.rst
+
+The styles in ``thumbs.css`` are referenced in the :ref:`XBlock HTML file <The
+XBlock HTML File>`.
+
+.. include:: ../../links.rst