Merge pull request #692 from openedx/sarina/improve-tutorial

docs: Improve XBlock tutorial sections 1-3

docs/links.rst

@@ -31,6 +31,8 @@
 
 .. _VirtualEnvWrapper: http://virtualenvwrapper.readthedocs.io/en/latest
 
+.. _managing different Python versions with virtualenv: https://saturncloud.io/blog/how-to-use-different-python-versions-with-virtualenv/
+
 .. _XBlock SDK: https://github.com/openedx/xblock-sdk
 
 .. _PyEnv: https://github.com/yyuu/pyenv
@@ -45,6 +47,8 @@
 
 .. _View Counter XBlock: https://github.com/openedx/xblock-sdk/blob/master/sample_xblocks/basic/view_counter.py
 
+.. _Google Drive and Calendar XBlock: https://github.com/openedx/xblock-google-drive
+
 .. _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
@@ -62,3 +66,5 @@
 .. _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
+
+.. _HTML unicode characters: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references

docs/xblock-tutorial/anatomy/javascript.rst

@@ -8,13 +8,13 @@ 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``.
+this file locally at ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/src/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``
+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>`
@@ -29,7 +29,7 @@ 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
+* The ``ThumbsBlock`` function maps to the constructor in the :ref:`XBlock
   Python file <The XBlock Python File>` and provides access to its methods and
   fields.
 
@@ -39,7 +39,7 @@ Note the following details about the JavaScript file.
 
     var handlerUrl = runtime.handlerUrl(element, 'vote');
   
-* The ``ThumbsBlock`` function includes the ``Post`` commands to increase the up
+* 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``

docs/xblock-tutorial/anatomy/python.rst

@@ -1,8 +1,8 @@
 .. _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.
@@ -18,9 +18,9 @@ scenarios.
  :local:
  :depth: 1 
 
-********************
+*******************
 Thumb XBlock Fields
-********************
+*******************
 
 The ``thumbs.py`` file defines the following fields for the XBlock in the
 ``ThumbsBlockBase`` class.
@@ -42,9 +42,9 @@ Note the following details about the fields in the Thumbs XBlock.
 
 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. 
@@ -60,24 +60,28 @@ Note the following details about student view.
 
   .. code-block:: python
 
-     html_str = pkg_resources.resource_string(__name__, "static/html/thumbs.html")
-     frag = Fragment(unicode(html_str).format(self=self))
+     html_str = pkg_resources.resource_string(
+          __name__,
+          "static/html/thumbs.html".decode('utf-8')
+      )
+     frag = Fragment(str(html_str).format(block=self))
 
 *  The JavaScript and CSS file contents 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 in the :ref:`JavaScript file <The XBlock JavaScript File>`.
+  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.
 

docs/xblock-tutorial/concepts/fields.rst

@@ -260,9 +260,9 @@ You can customize the OLX representation of the XBlock by using the
 Field Requirements in the edX Platform
 **************************************
 
-For information about field requirements in the edX Platform, see :ref:`edX LMS
-<EdX Learning Management System as an XBlock Runtime>` and
-:ref:`edX Studio <EdX Studio as an XBlock Runtime>`.
+For information about field requirements in the edX Platform, see :ref:`Open edX LMS
+<Open edX Learning Management System as an XBlock Runtime>` and
+:ref:`Open edX Studio <Open edX Studio as an XBlock Runtime>`.
 
 ******************************
 Default Fields in a New XBlock

docs/xblock-tutorial/concepts/methods.rst

@@ -10,7 +10,7 @@ XBlock.
 .. contents::
  :local:
  :depth: 1
-   
+
 .. _View Methods:
 
 ************
@@ -22,15 +22,15 @@ the XBlock.
 
 An XBlock can have multiple view methods. For example, an XBlock might have a
 student view for rendering the XBlock for learners, and an editing view for
-rendering the XBlock to course staff. 
+rendering the XBlock to course staff.
 
-.. note:: 
-  The XBlock view names are specified by runtime applications; you cannot use 
-  arbitrary view names. 
+.. note::
+  The XBlock view names are specified by runtime applications; you cannot use
+  arbitrary view names.
 
-For information about the view requirements in the edX Platform, see :ref:`edX
-LMS <EdX Learning Management System as an XBlock Runtime>` and
-:ref:`edX Studio <EdX Studio as an XBlock Runtime>`.
+For information about the view requirements in the edX Platform, see :ref:`Open edX
+LMS <Open edX Learning Management System as an XBlock Runtime>` and
+:ref:`Open edX Studio <Open edX Studio as an XBlock Runtime>`.
 
 Typically, you define a view to produce a fragment that is used to render the
 XBlock as part of a web page. Fragments are aggregated hierarchically. You can
@@ -104,12 +104,12 @@ Default Methods in a New XBlock
 When you create a new XBlock, two methods are added automatically.
 
 * The view method ``student_view``.
-  
+
   You can modify the contents of this view, but to use your XBlock with the edX
   Platform, you must keep the method name ``student_view``.
 
-* The handler method ``increment_count``. 
-  
+* The handler method ``increment_count``.
+
   This method is for demonstration purposes and you can remove it.
 
 

docs/xblock-tutorial/concepts/runtimes.rst

@@ -5,8 +5,8 @@ XBlock Runtimes
 ###############
 
 An XBlock runtime is the application that hosts XBlock. For example, the XBlock
-SDK, the :ref:`edX LMS <EdX Learning Management System as an XBlock Runtime>`,
-and :ref:`edX Studio <EdX Studio as an XBlock Runtime>` are all XBlock runtime
+SDK, the :ref:`Open edX LMS <Open edX Learning Management System as an XBlock Runtime>`,
+and :ref:`Open edX Studio <Open edX Studio as an XBlock Runtime>` are all XBlock runtime
 applications. You can also render an individual XBlock in HTML with the XBlock
 URL.
 

docs/xblock-tutorial/customize/custom-html.rst

@@ -17,9 +17,9 @@ method <View Methods>`.
  :local:
  :depth: 1 
 
-*******************************
+****************************
 The Default XBlock HTML File
-*******************************
+****************************
 
 When you :ref:`create a new XBlock <Create Your First XBlock>`, the default
 static HTML file is created automatically, with skeletal functionality defined.
@@ -31,9 +31,9 @@ file ``myxblock.html``.
 The file contains HTML to display the ``count`` field that was added by
 default to the XBlock. Delete the HTML between the ``div`` elements.
 
-********************
+****************
 Add HTML Content
-********************
+****************
 
 You can create HTML as needed to display the state of your XBlock. The Thumbs
 XBlock displays the up and down votes. Create a single paragraph and follow the
@@ -50,13 +50,13 @@ guidelines below.
   reference the ``upvotes`` and ``downvotes`` fields you defined in the
   :ref:`Python file <Customize myxblock.py>` for the XBlock.
 
-* For the value of each of the outer ``span`` elements, use the entities
-  ``&uarr;`` and ``&darr`` to show thumbs up and thumbs down symbols next to
-  the number of votes.
+* For the value of each of the outer ``span`` elements, use the `HTML unicode
+  characters`_ ``&uarr;`` and ``&darr`` to show thumbs up and thumbs down
+  symbols next to the number of votes.
 
-****************************************
+************************************
 Check HTML Against the Thumbs XBlock
-****************************************
+************************************
 
 After you have defined the HTML, check your work against the HTML in the
 Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/html/thumbs.html``.
@@ -66,11 +66,11 @@ Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs
 If necessary, make corrections to the HTML in your XBlock so that it
 matches the HTML in the Thumbs XBlock.
 
-**********************************
+*********
 Next Step
-**********************************
+*********
 
-After you complete your customizations to the HTML file, you continue on and
+After you complete your customizations to the HTML file, you can continue on and
 :ref:`customize the XBlock JavaScript file<Customize myxblock.js>`.
 
 .. include:: ../../links.rst

docs/xblock-tutorial/customize/custom-javascript.rst

@@ -1,8 +1,8 @@
 .. _Customize myxblock.js:
 
-#######################
+#####################
 Customize myxblock.js
-#######################
+#####################
 
 This section describes how to modify the JavaScript file of the XBlock you
 created, ``myxblock.js``, to provide the functionality in the Thumbs XBlock
@@ -16,23 +16,23 @@ Fragments>`.
  :local:
  :depth: 1 
 
-***********************************
+**********************************
 The Default XBlock JavaScript File
-***********************************
+**********************************
 
 When you :ref:`create a new XBlock <Create Your First XBlock>`, the default
 JavaScript file is created automatically, with skeletal functionality defined.
-In the ``xblock_development/myxblock/myxblock/static/js/source`` directory, see
+In the ``xblock_development/myxblock/myxblock/static/js/snc`` directory, see
 the file ``myxblock.js``.
 
 .. include:: ../reusable/code_myxblock_js.rst
 
 The file contains JavaScript code to increment the ``count`` field that was
 added by default to the XBlock. Delete this code.
 
-********************
+*******************
 Add JavaScript Code
-********************
+*******************
 
 JavaScript code implements the browser-side functionality you need for your
 XBlock. The Thumbs XBlock uses clicks on the up and down vote buttons to call
@@ -52,28 +52,28 @@ Follow the guidelines below to implement JavaScript code.
 
     var handlerUrl = runtime.handlerUrl(element, 'vote');
   
-* Add ``Post`` commands in the ``MyXBlock`` function to increase the up and
+* Add ``POST`` commands in the ``MyXBlock`` function to increase the up and
   down votes in the XBlock.
 
   .. note:: Do not change the main function name, ``MyXBlock``.
 
-*******************************************
+******************************************
 Check JavaScript Against the Thumbs XBlock
-*******************************************
+******************************************
 
 After you have defined the JavaScript code, check your work against the code in
-the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/source/thumbs.js``.
+the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/src/thumbs.js``.
 
 .. include:: ../reusable/code_thumbs_javascript.rst
 
 If necessary, make corrections to the code in your XBlock so that it
 matches the code in the Thumbs XBlock.
 
-**********************************
+*********
 Next Step
-**********************************
+*********
 
-After you complete your customizations to the JavaScript file, you continue on
+After you complete your customizations to the JavaScript file, you can continue on
 and :ref:`customize the XBlock CSS file<Customize myxblock.css>`.
 
 .. include:: ../../links.rst