Merge pull request #2614 from edx/sylvia/documentation/BLD-815

Sylvia/documentation/bld 815

docs/en_us/course_authors/source/additional_tools.rst

@@ -9,11 +9,12 @@ Additional Tools
 Additional Tools Overview
 *************************
 
-Individual course teams frequently create tools and problem types that don't have templates in Studio. We want to make these tools available to all our course teams. We provide you with all the files and code that you need to create these problems in Studio.
+Individual course teams frequently create tools and problem types that don't have templates in Studio. We want to make these tools available to all our course teams. 
 
-Below, you'll find the information you need to create the following tools.
+Below, we provide you with all the files and code that you need to create the following tools and problem types.
 
 * :ref:`Gene Explorer`
+* :ref:`Chemical Equation`
 * :ref:`Interactive Periodic Table`
 * :ref:`Molecule Editor`
 * :ref:`Multiple Choice and Numerical Input`
@@ -41,18 +42,6 @@ Specifically, the Gene Explorer does the following:
 
 For more information about the Gene Explorer, see `The Gene Explorer <http://intro.bio.umb.edu/GX/>`_.
 
-.. _Create the Gene Explorer:
-
-==========================
-Create the Gene Explorer
-==========================
-
-#. In the unit where you want to create the problem, click **Problem** under **Add New Component**, and then click the **Advanced** tab.
-#. Click **Blank Advanced Problem**.
-#. In the component that appears, click **Edit**.
-#. In the component editor, paste the code from below.
-#. Click **Save**.
-
 =====================
 Gene Explorer Code
 =====================
@@ -82,6 +71,76 @@ In this code:
 * **genex_problem_number** specifies the number of the problem. This number is based on the five gene editor problems in the MITx 7.00x course--for example, if you want this problem to look like the second gene editor problem in the 7.00x course, you would set the **genex_problem_number** value to 2. The number must be 1, 2, 3, 4, or 5.
 
 
+.. _Chemical Equation:
+
+**************************
+Chemical Equation Problem
+**************************
+
+The chemical equation problem type allows the student to enter chemical equations. The grader evaluates student responses by using a Python script that you create and embed in the problem.
+
+.. image:: /Images/ChemicalEquationExample.png
+ :alt: Image of a chemical equation response problem
+
+====================================
+Create the Chemical Equation Problem
+====================================
+
+To create the above chemical equation problem:
+
+#. In the unit where you want to create the problem, click **Problem** under **Add New Component**, and then click the **Advanced** tab.
+#. Click **Blank Advanced Problem**.
+#. In the component that appears, click **Edit**.
+#. In the component editor, paste the code from below.
+#. Click **Save**.
+
+
+
+
+
+====================================
+Chemical Equation Problem Code
+====================================
+
+.. code-block:: xml
+
+  <problem>
+    <startouttext/>
+    <p>Some problems may ask for a particular chemical equation. Practice by writing out the following reaction in the box below.</p>
+    
+  \( \text{H}_2\text{SO}_4 \longrightarrow \text { H}^+ + \text{ HSO}_4^-\)
+
+    <customresponse>
+      <chemicalequationinput size="50"/>
+      <answer type="loncapa/python">
+
+  if chemcalc.chemical_equations_equal(submission[0], 'H2SO4 -> H^+ + HSO4^-'):
+      correct = ['correct']
+  else:
+      correct = ['incorrect']
+
+      </answer>
+    </customresponse>
+    <p>Some tips:</p>
+    <ul>
+    <li>Use real element symbols.</li>
+    <li>Create subscripts by using plain text.</li>
+    <li>Create superscripts by using a caret (^).</li>
+    <li>Create the reaction arrow (\(\longrightarrow\)) by using "->".</li>
+    </ul>
+
+    <endouttext/>
+  
+   <solution>
+   <div class="detailed-solution">
+   <p>Solution</p>
+   <p>To create this equation, enter the following:</p>
+     <p>H2SO4 -> H^+ + HSO4^-</p>
+   </div>
+   </solution>
+  </problem>
+
+
 .. _Interactive Periodic Table:
 
 **************************
@@ -116,7 +175,7 @@ To create the periodic table, you need an HTML component.
 #. In the component editor, switch to the **HTML** tab.
 #. Open the PeriodicTable.txt file in any text editor.
 #. Copy all of the text in the PeriodicTable.txt file, and paste it into the HTML component editor. (Note that the PeriodicTableHTML.txt file contains over 6000 lines of code. Paste all of this code into the component editor.)
-#. Make any changes that you want, and then click **Save**.
+#. Click **Save**.
 
 .. _Molecule Editor:
 
@@ -151,15 +210,18 @@ To create the molecule editor that appears in the image above, you need an HTML
 
 #. Upload all of the files listed above to the **Files & Uploads** page in your course.
 #. Create the HTML component.
+
   #. In the unit where you want to create the problem, click **HTML** under **Add New Component**, and then click **HTML**.
   #. In the component that appears, click **Edit**.
   #. In the component editor, paste the HTML component code from below.
   #. Make any changes that you want, and then click **Save**.
-#. Create the Problem component.
+
+3. Create the Problem component.
+
   #. Under the HTML component, click **Problem** under **Add New Component**, and then click **Blank Advanced Problem**.
   #. In the component that appears, click **Edit**.
   #. In the component editor, paste the Problem component code from below.
-  #. Make any changes that you want, and then click **Save**.
+  #. Click **Save**.
 
 .. _EMC Problem Code:
 
@@ -172,7 +234,7 @@ To create the molecule editor, you need an HTML component and a Problem componen
 HTML Component Code
 -------------------
 
-::
+.. code-block:: xml
 
   <h2>Molecule Editor</h2>
   <p>The molecule editor makes creating and visualizing molecules easy. A chemistry professor may have you build and submit a molecule as part of an exercise.</p>
@@ -215,12 +277,12 @@ HTML Component Code
   </div>
   <div id="ap_listener_added">&nbsp;</div>
 
-Problem Component
------------------
 
-**Problem 1**
 
-::
+
+Problem Component Code
+----------------------
+.. code-block:: xml
 
   <problem>
   <p>The dopamine molecule, as shown, cannot make ionic bonds. Edit the dopamine molecule so it can make ionic bonds.</p>
@@ -313,7 +375,7 @@ To create a multiple choice and numerical input problem:
 Multiple Choice and Numerical Input Problem Code
 ===================================================
 
-::
+.. code-block:: xml
 
   <problem>
   The numerical value of pi, rounded to two decimal points, is 3.24.
@@ -356,7 +418,7 @@ To create the protein builder:
 Protein Builder Code
 =====================
 
-::
+.. code-block:: xml
 
   <problem>
       <p>The protein builder allows you string together the building blocks of proteins, amino acids, and see how that string will form into a structure. You are presented with a goal protein shape, and your task is to try to re-create it. In the example below, the shape that you are asked to form is a simple line.</p> 

docs/en_us/course_authors/source/change_log.rst

@@ -4,7 +4,6 @@
 Change Log
 **********
 
-
 .. list-table::
    :widths: 10 80
    :header-rows: 1
@@ -12,10 +11,12 @@ Change Log
    * - Date
      - Change
    * - 02/14/14
-     - Added :ref:`Additional Transcripts` section to :ref:`Working with Video Components`; updated :ref:`Video Advanced Options` 
+     - Added :ref:`Additional Transcripts` section to :ref:`Working with Video Components`; 
+       updated :ref:`Video Advanced Options` 
+   * -
      - Added the :ref:`Course Data`, :ref:`Course_Staffing`, and :ref:`Enrollment` chapters. 
    * - 02/11/14
-     - Added :ref:`Gene Editor` and updated :ref:`Interactive Periodic Table` and :ref:`Molecule Editor` in :ref:`Additional Tools`
+     - Added :ref:`Gene Explorer` and updated :ref:`Interactive Periodic Table` and :ref:`Molecule Editor` in :ref:`Additional Tools`
    * - 02/07/14
      - Added section on :ref:`Full Screen Image`.
    * - 02/06/14

docs/en_us/course_authors/source/common_problems.rst

@@ -398,7 +398,7 @@ Case Sensitivity and Text Input Problems
 By default, text input problems do not require a case sensitive response. You can change this
 and require a case sensitive answer.
 
-To make a text input response case sensitive, you must use the :ref:`Advanced Editor`.
+To make a text input response case sensitive, you must use :ref:`Advanced Editor`.
 
 In the advanced editor, you see that the **type** attribute of the **stringresponse** 
 element equals **ci**, for *case insensitive*. For example:
@@ -426,7 +426,7 @@ By default, the response field for text input problems is 20 characters long.
 You should preview the unit to ensure that the length of the response input field
 accommodates the correct answer, and provides extra space for possible incorrect answers.
 
-If the default response field length is not sufficient, you can change it using the :ref:`Advanced Editor`.
+If the default response field length is not sufficient, you can change it using :ref:`Advanced Editor`.
 
 In the advanced editor, in the XML block for the answer, you see that the **size** attribute of the **textline** 
 element equals **20**:
@@ -444,3 +444,9 @@ To change the response field length, change the value of the **size** attribute:
     <stringresponse answer="Democratic Republic of the Congo" type="ci">
       <textline size="40"/>
     </stringresponse>
+
+====================================================
+Hints and Regular Expressions in Text Input Problems
+====================================================
+
+You can provide hints for common incorrect answers in text input problems. You can also set a text input problem to allow a regular expression as an answer. To do this, you'll have to modify the problem's XML in the Advanced Editor. For more information, see :ref:`String Response`.
\ No newline at end of file

docs/en_us/course_authors/source/conf.py

@@ -3,24 +3,37 @@
 
 import sys, os
 
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 
-sys.path.append(os.path.abspath('../../../../'))
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+
+
+
+
+
+
+
 sys.path.append(os.path.abspath('../../../'))
+sys.path.append(os.path.abspath('../../'))
 
-from docs.shared.conf import *
+#from docs.shared.conf import *
 
 sys.path.insert(0, os.path.abspath('.'))
 
 master_doc = 'index'
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path.append('source/_templates')
+#templates_path.append('source/_templates')
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path.append('source/_static')
+#html_static_path.append('source/_static')
 
 
 # General information about the project.

docs/en_us/course_authors/source/course_data.rst

@@ -24,4 +24,3 @@ To view course data:
 
 .. You also use the Instructor Dashboard to set up the staff for your course, enroll students and access student data, and initiate, review, and adjust grades.
 
-**Question**: I initially thought that there was enough information available about the course as a whole to make this into a longer chapter. Am I missing features or tasks that instructors use to get information about a course? It doesn't have to be something accessible on the instructor dashboard, but just info that might be useful while a course is running...
\ No newline at end of file

docs/en_us/course_authors/source/discussions.rst

@@ -190,7 +190,7 @@ To encourage longer, threaded discussions rather than many similar, separate pos
   You can respond to a redundant post or response by pasting in a link to the thread that you prefer students to contribute to, and then prevent further thread interaction by closing the entire post or a specific response. Click the **Close** button that displays below the post or response to close it. 
 
 * Provide post/response/comment guidelines.
-  A set of :ref:`Discussion Forum Guidelines` or a post in the General discussion can provide guidance about when to create a new thread, respond to an existing post, or comment on a response. 
+  A set of :ref:`Guidance for Discussion Moderators` or a post in the General discussion can provide guidance about when to create a new thread, respond to an existing post, or comment on a response. 
 
 
 .. _Moderating_discussions:

docs/en_us/course_authors/source/glossary.rst

@@ -61,7 +61,7 @@ C
  
 **Chemical Equation Response Problem**
 
-  A problem that allows the student to enter chemical equations as answers. For more information, see :ref:`Chemical Equation Response`.
+  A problem that allows the student to enter chemical equations as answers. For more information, see :ref:`Chemical Equation`.
 
 
 .. _Circuit Schematic Builder Problem: