docs: move xblock tutorial from old docs site

docs/index.rst

@@ -1,14 +1,14 @@
 .. _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/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/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/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/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/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/links.rst

docs/xblock-tutorial/concepts/children.rst

@@ -0,0 +1,74 @@
+.. _XBlock Children:
+
+####################
+XBlock Children
+####################
+
+An XBlock can have child XBlocks. 
+
+.. contents::
+ :local:
+ :depth: 1
+
+**********************
+XBlock Tree Structure
+**********************
+
+An XBlock does not refer directly to its children. Instead, the structure of a
+tree of XBlocks is maintained by the runtime application, and is made available
+to the XBlock through a runtime service. For more information, see :ref:`XBlock
+Runtimes`.
+
+This allows the runtime to store, access, and modify the structure of a course
+without incurring the overhead of the XBlock code itself.
+
+XBlock children are not implicitly available to their parents. The runtime
+provides the parent XBlock with a list of child XBlock IDs. The child XBlock
+can then be loaded with the ``get_child()`` function. Therefore the runtime can
+defer loading child XBlocks until they are actually required.
+
+.. example?
+
+********************************
+Accessing Children (Server-Side)
+********************************
+
+To access XBlock children through the server, use the following methods.
+
+* To iterate over the XBlock’s children, use ``self.get_children`` which
+  returns the IDs for each child XBlock.
+
+* Then, to access a child XBlock, use ``self.get_child(usage_id)`` for
+  your desired ID. You can then modify the child XBlock using its ``.save()``
+  method.
+
+* To render a given child XBlock, use ``self.runtime.render_child(usage_id)``.
+
+* To render all children for a given XBlock, use
+  ``self.runtime.render_children()``.
+
+* To ensure the XBlock children are rendered correctly, add the
+  ``fragment.content`` into the parent XBlock's HTML file, then use
+  ``fragment.add_frag_resources()`` (or ``.add_frags_resources()``, to render
+  all children). This ensures that the JavaScript and CSS of child elements are
+  included.
+
+.. examples?
+
+********************************
+Accessing Children (Client-Side)
+********************************
+
+To access XBlock children through the client, with JavaScript, use the
+following methods.
+
+* Use ``runtime.children(element)``, where ``element`` is the DOM node that
+  contains the HTML representation of your XBlock’s server-side view.
+  (``runtime`` is automatically provided by the XBlock runtime.)
+
+* Similarly, you can use ``runtime.childMap(element, name)`` to get a child
+  element that has a specific name. 
+
+.. examples?
+
+.. include:: ../../../links/links.rst