Skip to content

E
edx-platform
Commit a2f88248 by Mark Hoeber
Options

Merge pull request #3581 from edx/markhoeber/documentation/doc-332 

Markhoeber/documentation/doc 332
parents 692e4b2e 3635f9ce
Showing with 66 additions and 461 deletions
docs/en_us/data/README deleted 100644 → 0
This directory contains some high level documentation for the code.
WARNING: much of this is out-of-date. It still may be helpful, though.
docs/en_us/data/source/conf.py
......@@ -35,7 +35,7 @@ master_doc = 'index'
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path.append('source/_static')
project = u'edX Data Documentation'
project = u'edX Research Guide'
copyright = u'2014, edX'
# The short X.Y version.
......
docs/en_us/data/source/course_data_formats/conditional_module/conditional_module.rst deleted 100644 → 0
**********************************************
Xml format of conditional module [xmodule]
**********************************************
.. module:: conditional_module
Format description
==================
The main tag of Conditional module input is:
.. code-block:: xml
<conditional> ... </conditional>
``conditional`` can include any number of any xmodule tags (``html``, ``video``, ``poll``, etc.) or ``show`` tags.
conditional tag
---------------
The main container for a single instance of Conditional module. The following attributes can
be specified for this tag::
sources - location id of required modules, separated by ';'
[message | ""] - message for case, where one or more are not passed. Here you can use variable {link}, which generate link to required module.
[submitted] - map to `is_submitted` module method.
(pressing RESET button makes this function to return False.)
[correct] - map to `is_correct` module method
[attempted] - map to `is_attempted` module method
[poll_answer] - map to `poll_answer` module attribute
[voted] - map to `voted` module attribute
show tag
--------
Symlink to some set of xmodules. The following attributes can
be specified for this tag::
sources - location id of modules, separated by ';'
Example
=======
Examples of conditional depends on poll
-------------------------------------------
.. code-block:: xml
<conditional sources="i4x://MITx/0.000x/poll_question/first_real_poll_seq_with_reset" poll_answer="man"
message="{link} must be answered for this to become visible.">
<html>
<h2>You see this, cause your vote value for "First question" was "man"</h2>
</html>
</conditional>
Examples of conditional depends on poll (use <show> tag)
--------------------------------------------------------
.. code-block:: xml
<conditional sources="i4x://MITx/0.000x/poll_question/first_real_poll_seq_with_reset" poll_answer="man"
message="{link} must be answered for this to become visible.">
<html>
<show sources="i4x://MITx/0.000x/problem/test_1; i4x://MITx/0.000x/Video/Avi_resources; i4x://MITx/0.000x/problem/test_1"/>
</html>
</conditional>
Examples of conditional depends on problem
-------------------------------------------
.. code-block:: xml
<conditional sources="i4x://MITx/0.000x/problem/Conditional:lec27_Q1" attempted="True">
<html display_name="HTML for attempted problem">You see this, cause "lec27_Q1" is attempted.</html>
</conditional>
<conditional sources="i4x://MITx/0.000x/problem/Conditional:lec27_Q1" attempted="False">
<html display_name="HTML for not attempted problem">You see this, cause "lec27_Q1" is not attempted.</html>
</conditional>
docs/en_us/data/source/course_data_formats/custom_response.rst deleted 100644 → 0
####################################
CustomResponse XML and Python Script
####################################
This document explains how to write a CustomResponse problem. CustomResponse
problems execute Python script to check student answers and provide hints.
There are two general ways to create a CustomResponse problem:
*****************
Answer tag format
*****************
One format puts the Python code in an ``<answer>`` tag:
.. code-block:: xml
<problem>
<p>What is the sum of 2 and 3?</p>
<customresponse expect="5">
<textline math="1" />
</customresponse>
<answer>
# Python script goes here
</answer>
</problem>
The Python script interacts with these variables in the global context:
* ``answers``: An ordered list of answers the student provided.
For example, if the student answered ``6``, then ``answers[0]`` would
equal ``6``.
* ``expect``: The value of the ``expect`` attribute of ``<customresponse>``
(if provided).
* ``correct``: An ordered list of strings indicating whether the
student answered the question correctly. Valid values are
``"correct"``, ``"incorrect"``, and ``"unknown"``. You can set these
values in the script.
* ``messages``: An ordered list of message strings that will be displayed
beneath each input. You can use this to provide hints to users.
For example ``messages[0] = "The capital of California is Sacramento"``
would display that message beneath the first input of the response.
* ``overall_message``: A string that will be displayed beneath the
entire problem. You can use this to provide a hint that applies
to the entire problem rather than a particular input.
Example of a checking script:
.. code-block:: python
if answers[0] == expect:
correct[0] = 'correct'
overall_message = 'Good job!'
else:
correct[0] = 'incorrect'
messages[0] = 'This answer is incorrect'
overall_message = 'Please try again'
**Important**: Python is picky about indentation. Within the ``<answer>`` tag,
you must begin your script with no indentation.
*****************
Script tag format
*****************
The other way to create a CustomResponse is to put a "checking function"
in a ``<script>`` tag, then use the ``cfn`` attribute of the
``<customresponse>`` tag:
.. code-block:: xml
<problem>
<p>What is the sum of 2 and 3?</p>
<customresponse cfn="check_func" expect="5">
<textline math="1" />
</customresponse>
<script type="loncapa/python">
def check_func(expect, ans):
# Python script goes here
</script>
</problem>
**Important**: Python is picky about indentation. Within the ``<script>`` tag,
the ``def check_func(expect, ans):`` line must have no indentation.
The check function accepts two arguments:
* ``expect`` is the value of the ``expect`` attribute of ``<customresponse>``
(if provided)
* ``answer`` is either:
* The value of the answer the student provided, if there is only one input.
* An ordered list of answers the student provided, if there
are multiple inputs.
There are several ways that the check function can indicate whether the student
succeeded. The check function can return any of the following:
* ``True``: Indicates that the student answered correctly for all inputs.
* ``False``: Indicates that the student answered incorrectly.
All inputs will be marked incorrect.
* A dictionary of the form: ``{ 'ok': True, 'msg': 'Message' }``
If the dictionary's value for ``ok`` is set to ``True``, all inputs are
marked correct; if it is set to ``False``, all inputs are marked incorrect.
The ``msg`` is displayed beneath all inputs, and it may contain
XHTML markup.
* A dictionary of the form
.. code-block:: xml
{ 'overall_message': 'Overall message',
'input_list': [
{ 'ok': True, 'msg': 'Feedback for input 1'},
{ 'ok': False, 'msg': 'Feedback for input 2'},
... ] }
The last form is useful for responses that contain multiple inputs.
It allows you to provide feedback for each input individually,
as well as a message that applies to the entire response.
Example of a checking function:
.. code-block:: python
def check_func(expect, answer_given):
check1 = (int(answer_given[0]) == 1)
check2 = (int(answer_given[1]) == 2)
check3 = (int(answer_given[2]) == 3)
return {'overall_message': 'Overall message',
'input_list': [
{ 'ok': check1, 'msg': 'Feedback 1'},
{ 'ok': check2, 'msg': 'Feedback 2'},
{ 'ok': check3, 'msg': 'Feedback 3'} ] }
The function checks that the user entered ``1`` for the first input,
``2`` for the second input, and ``3`` for the third input.
It provides feedback messages for each individual input, as well
as a message displayed beneath the entire problem.
docs/en_us/data/source/course_data_formats/formula_equation_input.rst deleted 100644 → 0
Formula Equation Input
######################
Tag: ``<formulaequationinput />``
The formula equation input is a math input type used with Numerical and Formula
responses only. It is not to be used with Symoblic Response. It is comparable
to a ``<textline math="1"/>`` but with a different means to display the math.
It lets the platform validate the student's input as she types.
This is achieved by periodically sending the typed expression and requesting
its preview from the LMS. It parses the expression (using the same parser as
the parser it uses to eventually evaluate the response for grading), and sends
back an OK'd copy.
The basic appearance is that of a textbox with a preview box below it. The
student types in math (see note below for syntax), and a typeset preview
appears below it. Even complicated math expressions may be entered in.
For more information about the syntax, look in the course author's
documentation, under Appendix E, the section about Numerical Responses.
Format
******
The XML is rather simple, it is a ``<formulaequationinput />`` tag with an
optional ``size`` attribute, which defines the size (i.e. the width) of the
input box displayed to students for typing their math expression. Unlike
``<textline />``, there is no ``math`` attribute and adding such will have no
effect.
To see an example of the input type in context:
.. code-block:: xml
<problem>
<p>What base is the decimal numeral system in?</p>
<numericalresponse answer="10">
<formulaequationinput />
</numericalresponse>
<p>Write an expression for the product of R_1, R_2, and the inverse of R_3.</p>
<formularesponse type="ci" samples="R_1,R_2,R_3@1,2,3:3,4,5#10" answer="R_1*R_2/R_3">
<responseparam type="tolerance" default="0.00001"/>
<formulaequationinput size="40" />
</formularesponse>
</problem>
docs/en_us/data/source/course_data_formats/poll_module/poll_module.rst deleted 100644 → 0
**********************************************
Xml format of poll module [xmodule]
**********************************************
.. module:: poll_module
Format description
==================
The main tag of Poll module input is:
.. code-block:: xml
<poll_question> ... </poll_question>
``poll_question`` can include any number of the following tags:
any xml and ``answer`` tag. All inner xml, except for ``answer`` tags, we call "question".
poll_question tag
-----------------
Xmodule for creating poll functionality - voting system. The following attributes can
be specified for this tag::
name - Name of xmodule.
[display_name| AUTOGENERATE] - Display name of xmodule. When this attribute is not defined - display name autogenerate with some hash.
[reset | False] - Can reset/revote many time (value = True/False)
answer tag
----------
Define one of the possible answer for poll module. The following attributes can
be specified for this tag::
id - unique identifier (using to identify the different answers)
Inner text - Display text for answer choice.
Example
=======
Examples of poll
----------------
.. code-block:: xml
<poll_question name="second_question" display_name="Second question">
<h3>Age</h3>
<p>How old are you?</p>
<answer id="less18">&lt; 18</answer>
<answer id="10_25">from 10 to 25</answer>
<answer id="more25">&gt; 25</answer>
</poll_question>
Examples of poll with unable reset functionality
------------------------------------------------
.. code-block:: xml
<poll_question name="first_question_with_reset" display_name="First question with reset"
reset="True">
<h3>Your gender</h3>
<p>You are man or woman?</p>
<answer id="man">Man</answer>
<answer id="woman">Woman</answer>
</poll_question>
\ No newline at end of file
docs/en_us/data/source/course_data_formats/word_cloud/word_cloud.rst deleted 100644 → 0
**********************************************
Xml format of "Word Cloud" module [xmodule]
**********************************************
.. module:: word_cloud
Format description
==================
The main tag of Word Cloud module input is:
.. code-block:: xml
<word_cloud />
The following attributes can be specified for this tag::
[display_name| AUTOGENERATE] – Display name of xmodule. When this attribute is not defined - display name autogenerate with some hash.
[num_inputs| 5] – Number of inputs.
[num_top_words| 250] – Number of max words, which will be displayed.
[display_student_percents| True] – Display usage percents for each word on the same line together with words.
.. note::
Percent is shown always when mouse over the word in cloud.
.. note::
Possible answer for boolean type attributes:
True – "True", "true", "T", "t", "1"
False – "False", "false", "F", "f", "0"
.. note::
If you want to use the same word cloud (the same storage of words), you must use the same display_name value.
Code Example
============
Examples of word_cloud without all attributes (all attributes get by default)
-----------------------------------------------------------------------------
.. code-block:: xml
<word_cloud />
Examples of poll with all attributes
------------------------------------
.. code-block:: xml
<word_cloud display_name="cloud" num_inputs="10" num_top_words="100" />
Screenshots
===========
.. image:: word_cloud.png
:width: 50%
docs/en_us/data/source/index.rst
..
Public facing docs for non-developers go here. Please do not add any Python
dependencies for code introspection here (we may temporarily host it some
place where those dependencies are cumbersome to build).
######################
edX Research Guide
######################
edX Data Documentation
======================
The following documents are targeted at those who are working with various data formats consumed and produced by the edX platform -- primarily course authors and those who are conducting research on data in our system.
This document is intended for researchers and data czars at edX partner institutions who use the edX data exports to gain insight into their courses and students.
* If you are a course author working with course XML, see :ref:`Course Data Formats`.
* If you are a researcher working with data, see :ref:`Internal Data Formats`.
.. toctree::
:maxdepth: 2
Developer-oriented discussion of architecture and strictly internal APIs will be documented elsewhere.
read_me.rst
internal_data_formats/change_log.rst
internal_data_formats/data_czar.rst
internal_data_formats/sql_schema.rst
internal_data_formats/discussion_data.rst
internal_data_formats/wiki_data.rst
internal_data_formats/tracking_logs.rst
.. _Course Data Formats:
********************
Course Data Formats
-------------------
These are data formats written by people to specify course structure and content. Some of this is abstracted away if you are using the Studio authoring user interface.
********************
The `Building and Running an edX Course <http://edx.readthedocs.org/projects/ca/en/latest/>`_ guide provides complete information on how to construct a course.
The following sections of this document do not specifically pertain to researchers, but rather provide supplemental information on XML formats used to build an edX course. Over time, this information is being migrated to *Building and Running an edX Course*, as shown in the :ref:`Change Log`.
.. toctree::
:maxdepth: 2
course_data_formats/course_xml.rst
course_data_formats/grading.rst
Specific Problem Types
^^^^^^^^^^^^^^^^^^^^^^
.. toctree::
:maxdepth: 1
course_data_formats/drag_and_drop/drag_and_drop_input.rst
course_data_formats/graphical_slider_tool/graphical_slider_tool.rst
course_data_formats/poll_module/poll_module.rst
course_data_formats/lti_module/lti.rst
course_data_formats/conditional_module/conditional_module.rst
course_data_formats/word_cloud/word_cloud.rst
course_data_formats/custom_response.rst
course_data_formats/symbolic_response.rst
course_data_formats/formula_equation_input.rst
.. _Internal Data Formats:
Internal Data Formats
---------------------
These documents describe how we store course structure, student state/progress, and events internally. Useful for developers or researchers who interact with our raw data exports.
.. toctree::
:maxdepth: 2
internal_data_formats/change_log.rst
internal_data_formats/data_czar.rst
internal_data_formats/sql_schema.rst
internal_data_formats/discussion_data.rst
internal_data_formats/wiki_data.rst
internal_data_formats/tracking_logs.rst
Indices and tables
==================
* :ref:`search`
docs/en_us/data/source/internal_data_formats/change_log.rst
.. _Change Log:
**********
Change Log
......@@ -5,32 +6,41 @@ Change Log
.. list-table::
:widths: 15 75
:widths: 10 70
:header-rows: 1
* - Date
- Change
* - 29 Apr 14
* - 05/05/14
- Removed information on the Poll module. `Polls <http://edx.readthedocs.org/projects/ca/en/latest/exercises_tools/poll.html>`_ are now covered in the *Building and Running an edX Course* guide.
* -
- Removed information on the Word Cloud tool. The `Word Cloud tool <http://edx.readthedocs.org/projects/ca/en/latest/exercises_tools/word_cloud.html>`_ is now covered in the *Building and Running an edX Course* guide.
* -
- Removed information on CustomResponse XML and Python Script. See `Write-Your-Own-Grader Problem <http://edx.readthedocs.org/projects/ca/en/latest/exercises_tools/custom_python.html>`_ in the *Building and Running an edX Course* guide.
* -
- Removed information on Formula Equation Input. See `Create a Math Expression Input Problem <http://edx.readthedocs.org/projects/ca/en/latest/exercises_tools/math_expression_input.html>`_ in the *Building and Running an edX Course* guide.
* - 04/29/14
- Corrected misstatement on how :ref:`Discussion Forums Data` is sent in
data packages.
* - 25 Apr 14
* - 04/25/14
- Added new event types to the :ref:`Tracking Logs` chapter for interactions with PDF files.
* - 31 Mar 2014
* - 03/31/14
- Added new fields for the server ``problem_check`` event type to the :ref:`Tracking Logs` chapter.
* -
- Reformatted the :ref:`Tracking Logs` chapter to improve readability.
* - 28 Mar 2014
* - 03/28/14
- Added the :ref:'Data_Czar' chapter.
* - 24 Mar 2014
* - 03/24/14
- Added the ``user_api_usercoursetag`` table to the :ref:`Student_Info` chapter and the ``assigned_user_to_partition`` and ``child_render`` event types to the :ref:`Tracking Logs` chapter.
* - 19 Mar 2014
* - 03/19/14
- Provided alternative formatting for the examples in the :ref:`Discussion Forums Data` chapter.
* - 13 Mar 2014
* - 03/13/14
- Updated the :ref:`Student_Info` chapter.
* - 24 Feb 14
* - 02/24/14
- Added descriptions of new fields to the :ref:`Wiki_Data` chapter.
* - 21 Feb 2014
* - 02/21/14
- Added descriptions of new fields to the :ref:`Discussion Forums Data` chapter.
* - 14 Feb 2014
* - 02/14/14
- Added the ``seek_video`` and ``speed_change_video`` event types to the :ref:`Tracking Logs` chapter.
docs/en_us/data/source/internal_data_formats/data_czar.rst
......@@ -94,10 +94,10 @@ to set up a public/private key pair for GNU Privacy Guard (GNUPG).
* When a data package is available, the data czar downloads it from S3 and
decrypts it using the private key.
For detailed information on this procedure, see the *How Do I get my Research
Data Package?* article on the Open edX Analytics wiki_.
For detailed information on this procedure, see the `How Do I Get My Research
Data Package?`_ article on the Open edX Analytics wiki.
.. _wiki: https://edx-wiki.atlassian.net/wiki/pages/viewpage.action?pageId=36044863
.. _How Do I Get My Research Data Package?: https://edx-wiki.atlassian.net/wiki/pages/viewpage.action?pageId=36044863
.. _Resources_Information:
......@@ -110,11 +110,11 @@ list_ called course-data.
.. _list: http://groups.google.com/a/edx.org/forum/#!forum/course-data
EdX also hosts an **Open edX Analytics** wiki_ that is available to the
EdX also hosts an `Open edX Analytics wiki`_ that is available to the
public. The wiki provides links to the engineering roadmap, information about
operational issues, and release notes describing past releases.
.. _wiki: http://edx-wiki.atlassian.net/wiki/display/OA/Open+edX+Analytics+Home
.. _Open edX Analytics wiki: http://edx-wiki.atlassian.net/wiki/display/OA/Open+edX+Analytics+Home
.. _Skills_Experience_Contributors:
......
docs/en_us/data/source/read_me.rst 0 → 100644
*******
Read Me
*******
The *edX Research Guide* is created using RST_ files and Sphinx_. You, the
user community, can help update and revise this documentation project on
GitHub::
https://github.com/edx/edx-platform/tree/master/docs/course_authors/source
To suggest a revision, fork the project, make changes in your fork, and submit
a pull request back to the original project: this is known as the `GitHub Flow`_.
All pull requests need approval from edX. For more information, contact edX at `docs@edx.org`_.
.. _docs@edx.org: docs@edx.org
.. _Sphinx: http://sphinx-doc.org/
.. _LaTeX: http://www.latex-project.org/
.. _`GitHub Flow`: https://github.com/blog/1557-github-flow-in-the-browser
.. _RST: http://docutils.sourceforge.net/rst.html
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment