Skip to content

E
edx-platform
Commit cd9476b5 by Piotr Mitros Committed by Mark Hoeber
Options

First pass at improving OLX docs

parent e00b666d
Showing with 154 additions and 132 deletions
docs/en_us/olx/source/advanced-components/index.rst deleted 100644 → 0
.. _Advanced Components:
#################################
Advanced Components
#################################
Use the chapters in this section to create advanced course components.
.. toctree::
:maxdepth: 2
annotation
lti_component
open_response_assessment
word_cloud
\ No newline at end of file
docs/en_us/olx/source/components/discussion-components.rst
......@@ -2,7 +2,7 @@
Discussion Components
#################################
You can add inline discussion components to a vertical, or unit, in your
You can add inline discussion components to any container in your
course.
See:
......@@ -22,13 +22,26 @@ discussion component in your course.
The name of the XML file must match the value of the @url_name attribute of the
``discussion`` element in the vertical XML file.
For example, if the vertical XML file contains:
In-line, you can create, if the vertical XML file contains:
.. code-block:: xml
<vertical display_name="Lesson_1_Unit_1">
<discussion url_name="Introduce_Yourself"/>
. . .
<discussion
discussion_category="Essays"
discussion_id="peer_grading_component"
discussion_target="Peer Grading"
display_name="Peer Grading"
url_name="peer_grading_discussion"
/>
</vertical>
If you prefer to split this up, you can also create:
<vertical display_name="Lesson_1_Unit_1">
<discussion
url_name="Introduce_Yourself"
/>
</vertical>
You create the file ``discussion/Introduce_Yourself.xml`` to define the inline
......
docs/en_us/olx/source/components/html-components.rst
......@@ -4,7 +4,12 @@
HTML Components
#################################
To add an HTML component to your course, you create both XML and HTML files.
To add an HTML component to your course, you can either in-line it in
the parent XML file, or split it up into either 1 or 2 additional
files. HTML configuration can be broken out into a .xml file in the
html directory. In addition, HTML content can be broken out into an
additional .html file in the same directory. Breaking out HTML content
is especially useful if you are embedding HTML which is not valid XML.
See:
......@@ -15,11 +20,20 @@ See:
* `Create the HTML File for an HTML Component`_
* `Example HTML Component Content`_
*************************************
In-line HTML Example
*************************************
.. code-block:: xml
Both files, for each component, must be in the ``html`` directory.
<vertical display_name="Lesson_1_Unit_1">
...
<html>The above has an error. <b>x</b> should be <b>y</b> in the second equation.</html>
</vertical>
*********************************************
Create the XML File for an HTML Component
Fully split HTML file example and explanation
*********************************************
You create an XML file in the ``html`` directory for each HTML component in your course.
......@@ -43,7 +57,7 @@ HTML Component XML File Elements
The root element of the XML file for the HTML component is file is ``html``.
The ``html`` element contains not children.
In this case, the ``html`` element contains no children.
*************************************
``html`` Element Attributes
......@@ -113,5 +127,3 @@ file for the edX Demo course:
&nbsp;They&rsquo;re fun to play with. &nbsp;Many courses will have tools
and labs that you need to use to complete homework assignments.</p>
docs/en_us/olx/source/components/index.rst
.. _Course Components:
#################################
Course Components
Course Components (XBlocks)
#################################
Use the chapters in this section to create course components.
Use the chapters in this section to create course components.
.. toctree::
:maxdepth: 2
......@@ -12,3 +12,14 @@ Use the chapters in this section to create course components.
html-components
discussion-components
video-components
annotation
lti_component
open_response_assessment
word_cloud
conditional_module
full_screen_image
google_hangout
periodic_table
poll
vitalsource
zooming_image
docs/en_us/olx/source/components/video-components.rst
......@@ -4,7 +4,9 @@
Video Components
#################################
You can add video components to a vertical, or unit, in your course.
You can add video components to any container in your course (such as
a vertical or sequential). Studio places all video components inside
verticals (which it calls units).
See:
......@@ -17,8 +19,18 @@ See:
Create the XML File for a Video Component
**********************************************
You create an XML file in the ``video`` directory for each video component in
your course.
If you wish to place a video in your course, add it to the course XML tree as:
<video
youtube="1.00:o2pLltkrhGM"
url_name="Introduction_Lecture"
display_name="Introduction Lecture"
youtube_id_1_0="o2pLltkrhGM"
</video>
If you would prefer to break this out into its own file, you create an
XML file in the ``video`` directory for each video component in your
course.
The name of the XML file must match the value of the @url_name attribute of the
``video`` element in the vertical XML file.
......
docs/en_us/olx/source/directory-structure.rst
.. _ODL Directory Structure with edX Studio:
###############################################
OLX Directory Structure
OLX Course Structure
###############################################
See:
......@@ -17,8 +17,6 @@ See:
* `tabs Directory`_
* `video Directory`_
****************************************
OLX and Directory File Structures
****************************************
......@@ -26,26 +24,27 @@ OLX and Directory File Structures
All files and sub-directories that comprise your OLX course are stored within
a single directory.
OLX provides for flexibility in the directory and file structure you use to
build your course.
OLX provides for some flexibility in the directory and file structure
you use to build your course.
************************
Top-level Directory
************************
In most cases, it is easiest to create your courseware structure in a
single file, the ``course.xml file``.
The ``course.xml`` file would contain the
definition of all chapters (sections), sequentials (subsections), and verticals
(units) in your courseware. The courseware structure would then refer to files
for components, which are stored in a directory for each type of XBlock.
Starting out, it is easiest to create your courseware structure in a
single file, the ``course.xml file``. This file may contain your
entire course, but in most cases, it is convenient to split out large
chunks of content into individual files. This is typically done either
at the level of large components, such as either problems or homework
assignments.
For example, the edX Platform contains a directory called `manual-testing-complete`_ that contains a course with all component types for testing
purposes.
Currently, Studio, on export, places each component in its own
file. MIT ODL and edX have scripts which rechunk the file structure in
different ways.
Course content, other than the courseware, is stored in separate directories
and files as shown in the rest of this chapter.
For example, the edX Platform contains a directory called
`manual-testing-complete`_ that contains a course with all component
types for testing purposes.
Following are descriptions of directories needed for a typical course. You
should set up these directories in preparation for developing your course
......@@ -56,9 +55,40 @@ content.
additional directories that store the XML for XBlocks of that type.
********************
``about`` Directory
XBlock directories (``html``, ``problem``, etc.)
********************
edX course components may be broken out of the main course.xml file
into individual files. Those files go into directories of the name of
the component type (XML tag). For example, components of type ``html``
may be placed as individual files in the ``html`` directory. If your
course does not contain html files, or if they are all in-lined in
their top-level components, you do not need to create an ``html``
directory.
For information about several examplars of these directories, see:
See :ref:`HTML Components` for more information.
See :ref:`Problems and Tools` for more information.
See :ref:`Video Components` for more information.
As the set of XBlocks grows, so does the set of associated XML tags
and directories.
********************
edX Platform Directories
********************
In addition to the course hierarchy, which is designed to be generic
and cross-platform, XML course exports contain a set of JSON and HTML
files providing edX-specific course metadata (such as course
information pages specific to a MOOC setting), as well as things which
have not yet been folded into the above framework.
====================
``about`` Directory
====================
The ``about`` directory contains:
* ``overview.html``, which contains the content for the course overview page
......@@ -70,21 +100,9 @@ The ``about`` directory contains:
See :ref:`The Course About Pages` for more information.
********************
``html`` Directory
********************
The ``html`` directory contains an HTML file for each HTML component in
the course.
If you do not need HTML components in the course, you do not need to create
this directory.
See :ref:`HTML Components` for more information.
********************
====================
``info`` Directory
********************
====================
The ``info`` directory contains:
......@@ -94,9 +112,9 @@ The ``info`` directory contains:
* ``updates.html``, which contains the course updates students see when opening
a course.
***********************
====================
``policies`` Directory
***********************
====================
The ``policies`` directory contains:
......@@ -109,46 +127,22 @@ The ``policies`` directory contains:
See :ref:`Course Policies` for more information.
**********************
``problem`` Directory
**********************
The ``problem`` directory contains an XML file for each problem component you
use in your course.
If you do not need problem components in the course, you do not need to create
this directory.
See :ref:`Problems and Tools` for more information.
********************
====================
``static`` Directory
********************
====================
The ``static`` directory contains the files used in your course, such as images
or PDFs.
See :ref:`Course Assets` for more information.
********************
====================
``tabs`` Directory
********************
====================
The ``tabs`` directory contains an HTML file for each page you add to your
course.
See :ref:`Course Pages` for more information.
********************
``video`` Directory
********************
The ``video`` directory contains an XML file for each video component you use
in your course.
If you do not need video components in the course, you do not need to create
this directory.
See :ref:`Video Components` for more information.
.. include:: links.rst
\ No newline at end of file
.. include:: links.rst
docs/en_us/olx/source/index.rst
......@@ -26,9 +26,8 @@ This document is intended for those developing edX courses through Open Learning
organizing-course/index
components/index
problem-xml/index
advanced-components/index
drafts/index
demo-course/index
\ No newline at end of file
docs/en_us/olx/source/organizing-course/course-structure-overview.rst
......@@ -16,19 +16,19 @@ Courseware
Courseware is the main content of your course, namely lessons and assessments.
The following list describes how courseware is organized in OLX:
* Course sections are at the top level of your course and typically represent a
time period. In OLX, sections are represented by ``chapter`` elements.
* Course chapters are at the top level of your course and typically
represent a time period. In Studio, chapters are called 'sections.'
* A section contains one or more subsections. Course subsections are parts of a
section, and usually represent a topic or other organizing principle. In
OLX, subsections are represented by ``sequential`` elements.
* A section contains one or more children which correspond to
top-level pages in the course. Studio calls these 'subsections' and
is currently restricted to ``sequential`` elements at this
level. OLX supports any XBlock at this level.
* A subsection contains one or more units. In OLX, units are represented by
``vertical`` elements.
* Course units are lessons in a subsection that students view as single pages.
A unit contains one or more components. Course components are objects within
units that contain your actual course content. For more information, see:
* Courses are composed of structural elements, such as ``sequential``
and ``vertical``, and leaf-nodes or content elements, such as
``html`` or ``problem``. Studio has a fixed hierarchy where children
of ``sequential`` elements are ``vertical`` elements (called units),
and children of ``vertical`` elements are leaf elements (called modules).
* :ref:`Course Components`
* :ref:`Problems and Tools`
......@@ -61,4 +61,4 @@ Course Policies
Course policies determine how your course functions. For example, policies
control grading and content experiments. For more information, see
:ref:`Policies`.
\ No newline at end of file
:ref:`Policies`.
docs/en_us/olx/source/organizing-course/course-xml-file.rst
......@@ -20,8 +20,6 @@ The ``course.xml`` File
The root element of the ``course.xml`` file is ``course``.
The ``course`` element does not contain any child elements.
For example, the ``course.xml`` file may contain:
.. code-block:: xml
......@@ -82,7 +80,7 @@ For example:
Course Chapters
*******************************
You create a course chapter with the ``chapter`` element, as a child of the root ``course`` element.
You create a course chapter with the ``chapter`` element, as a child of the root ``course`` element. Chapter elements are top-level pages in the course. The edX platform renders navigation chrome around them (tab-set on top and accordion on the left). It is possible to disable chrome for specific chapters using the ``chrome`` option. It is possible to associate chapters with different elements of the tabset with the ``default_tab`` option. It is possible to hide them from the navigation using the ``hide_from_toc`` option.
For example, if the course outline file contains:
......@@ -114,10 +112,7 @@ For example, if the course outline file contains:
``chapter`` Children
=========================
The ``chapter`` element contains one or more child ``sequential`` elements.
The ``sequential`` element references a sequential, or subsection, in the
course.
The ``chapter`` element contains one or more children. Studio uses ``sequential`` elements for all children of chapters, and calls these ``subsections``.
The following example shows a chapter with two sequentials, or subsections. :
......
docs/en_us/olx/source/pages/pages.rst
......@@ -4,7 +4,7 @@
Course Pages
#################################
You can add pages to your course. Each page appears in your course’s navigation
You can add tabs to your course. Each tab appears in your course’s navigation
bar.
*********************************************
......@@ -14,4 +14,7 @@ Create the Page File
You create an HTML file for each page you want to add to the course in the
``tabs`` directory.
You can add any text and HTML markup to the page.
\ No newline at end of file
You can add any text and HTML markup to the page. Tabs can also be
links, and other types of content. One common design pattern is to
link a tab to a chromeless XBlock in the courseware, which allows for
top-level interactive course content.
docs/en_us/olx/source/problem-xml/index.rst
.. _Problems and Tools:
#################################
Problems and Tools
Problems
#################################
Use the chapters in this section to create course problems and tools.
The format for edX problems is based on the LONCAPA XML format (https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro), although the two are not quite compatible. In the edX variant, problems are composed of four types of tags:
* inputtypes are similar to XBlocks. They define ways for users to enter input into the problem.
* responsetypes are graders. They define how inputs are mapped to grades.
* hinters are used to provide feedback to problems.
* Standard HTML tags are used for formatting.
In abstract, the system is designed to allow mixing-and-matching of inputtypes, responsetypes, and hinters. For example, a numerical grader could match 7+-0.1%. It would be okay to use this with any inputtype which output a number, whether this was a text box, equation input, slider, or multiple choice question. In practice, this doesn't always work. For example, in the former case, a multiple choice question would not give an output in a format a numerical grader could handle.
In addition, in many cases, there is a 1:1 mapping between graders and inputs. For some types of inputs (especially discipline-specific specialized ones), it simply does not make sense to have more than one grader.
The most general grader is customresponse. This uses a piece of Python code to evaluate the input. By design, this ought to work with any inputtype, although there are bugs mixing this with a small number of the newer inputtypes.
Like LON-CAPA, OLX allows embedding of code to generate parameterized problems. Unlike LON-CAPA, edX supports Python (and not Perl). Otherwise, the syntax is approximately identical.
.. toctree::
:maxdepth: 2
......@@ -12,16 +25,11 @@ Use the chapters in this section to create course problems and tools.
checkbox
chemical_equation
circuit_schematic_builder
conditional_module
custom_javascript
custom_python
drag_and_drop
dropdown
full_screen_image
gene_explorer
google_hangout
graphical_slider_tool
iframe
image_mapped_input
math_expression_input
mathjax
......@@ -29,12 +37,8 @@ Use the chapters in this section to create course problems and tools.
mult_choice_num_input
multiple_choice
numerical_input
periodic_table
poll
problem_in_latex
problem_with_hint
protein_builder
symbolic_response
text_input
vitalsource
zooming_image
\ 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