Show the docs some love

inducer · inducer · commit 4f10683abd01 · 2021-04-16T02:18:33.000-05:00
diff --git a/README.rst b/README.rst
@@ -46,9 +46,6 @@ features:
 * Facilitates live quizzes in the classroom.
 * In-class instant messaging via XMPP.
   Works well with `xmpp-popup <https://github.com/inducer/xmpp-popup>`_.
-* Built-in support for `VideoJS <http://www.videojs.com/>`_ offers
-  easy-to-use support for integrating HTML5 video into course content
-  without the need for third-party content hosting.
 
 Links
 -----
diff --git a/course/page/base.py b/course/page/base.py
@@ -82,7 +82,18 @@
 
 .. exception:: InvalidPageData
 
+Base Classes For Pages
+======================
+
 .. autoclass:: PageBase
+.. autoclass:: PageBaseWithTitle
+.. autoclass:: PageBaseWithHumanTextFeedback
+.. autoclass:: PageBaseWithCorrectAnswer
+
+Automatic Feedback
+==================
+
+.. autofunction:: get_auto_feedback
 """
 
 mark_safe_lazy = lazy(mark_safe, str)
diff --git a/course/page/choice.py b/course/page/choice.py
@@ -257,6 +257,29 @@ class ChoiceQuestion(ChoiceQuestionBase):
     """
     A page asking the participant to choose one of multiple answers.
 
+    Example:
+
+    .. code-block:: yaml
+
+        type: ChoiceQuestion
+        id: fp_accuracy
+        shuffle: True
+        prompt: |
+            # Floating point "machine epsilon"
+            For a (binary) floating point system of the form
+            $(s_1.s_2s_3)_2\\cdot 2^{p}$ that has an exponent range from $-128$ to
+            $127$ and that uses three bits to store the significand $s$, what is the
+            difference between 1 and the smallest representable number greater than
+            one?
+        choices:
+            - $2^{-3}$
+            - $2^{-4}$
+            - $2^{-1}$
+            - ~CORRECT~  $2^{-2}$
+        answer_explanation: |
+
+            That's just what it is.
+
     .. attribute:: id
 
         |id-page-attr|
diff --git a/course/page/code.py b/course/page/code.py
@@ -1072,6 +1072,41 @@ class PythonCodeQuestion(CodeQuestion):
     All user code as well as all code specified as part of the problem
     is in Python 3.
 
+    Example:
+
+    .. code-block:: yaml
+
+        type: PythonCodeQuestion
+        id: addition
+        access_rules:
+            add_permissions:
+                - change_answer
+        value: 1
+        timeout: 10
+        prompt: |
+            # Adding two numbers in Python
+            Your code will receive two variables, *a* and *b*. Compute their sum and
+            assign it to *c*.
+        setup_code: |
+            import random
+            a = random.uniform(-10, 10)
+            b = random.uniform(-10, 10)
+        names_for_user: [a, b]
+
+        correct_code: |
+            c = a + b
+        names_from_user: [c]
+
+        test_code: |
+            if not isinstance(c, float):
+                feedback.finish(0, "Your computed c is not a float.")
+            correct_c = a + b
+            rel_err = abs(correct_c-c)/abs(correct_c)
+            if rel_err < 1e-7:
+                feedback.finish(1, "Your computed c was correct.")
+            else:
+                feedback.finish(0, "Your computed c was incorrect.")
+
     If you are not including the
     :attr:`course.constants.flow_permission.change_answer`
     permission for your entire flow, you likely want to
diff --git a/course/page/inline.py b/course/page/inline.py
@@ -570,7 +570,9 @@ class InlineMultiQuestion(TextQuestionBase, PageBaseWithValue):
 
         Text justifying the answer, written in :ref:`markup`.
 
-    Here is an example of :class:`InlineMultiQuestion`::
+    Example:
+
+    .. code-block:: yaml
 
         type: InlineMultiQuestion
         id: inlinemulti
diff --git a/course/page/text.py b/course/page/text.py
@@ -814,7 +814,30 @@ def is_answer_gradable(self):
 
 class TextQuestion(TextQuestionBase, PageBaseWithValue):
     """
-    A page asking for a textual answer
+    A page asking for a textual answer.
+
+    Example:
+
+    .. code-block:: yaml
+
+        type: TextQuestion
+        id: fwd_err
+        prompt: |
+            # Forward Error
+            Consider the function $f(x)=1/x$, which we approximate by its Taylor
+            series about 1:
+            $$
+              f(x)\\approx 1-(x-1)+\\cdots
+            $$
+            What is the **forward error** of using this approximation at $x=0.5$?
+        answers:
+        -   type: float
+            value: 0.5
+            rtol: 0.01
+        -   <plain>HI THERE
+        answer_explanation: |
+
+            That's just what it is.
 
     .. attribute:: id
 
diff --git a/doc/faq.rst b/doc/faq.rst
@@ -1,5 +1,8 @@
 Frequently Asked Questions
-==========================
+##########################
+
+Getting Started
+===============
 
 How do I get started with Relate?
 ---------------------------------
@@ -61,7 +64,7 @@ Getting everything set up
 
         The course identifier is final and cannot be changed once the course
         is created.
-        
+
         When choosing the course identifier, note that this will appear as
         part of the URL when students browse your course, so it is best to
         choose something that is easy to type and does not look out of place
diff --git a/doc/flow-page-api.rst b/doc/flow-page-api.rst
@@ -1,8 +1,8 @@
 Internals
-^^^^^^^^^
+=========
 
 Flow Page Interface
-===================
+-------------------
 
 This describes the programming interface between Relate and a page in a flow.
 
@@ -13,23 +13,8 @@ Validation
 
 .. automodule:: course.validation
 
-Canonicalization of Django Names
-================================
-
-.. currentmodule:: django.forms.forms
-
-.. class:: Form
-
-    See :class:`django.forms.Form`.
-
-.. currentmodule:: django.http.request
-
-.. class:: HttpRequest
-
-    See :class:`django.http.HttpRequest`.
-
 Stub Docs
-=========
+---------
 
 .. currentmodule:: course.models
 
@@ -43,3 +28,18 @@ Stub Docs
 .. currentmodule:: course.utils
 
 .. class:: FlowPageContext
+
+Canonicalization of Django Names
+--------------------------------
+
+.. currentmodule:: django.forms.forms
+
+.. class:: Form
+
+    See :class:`django.forms.Form`.
+
+.. currentmodule:: django.http.request
+
+.. class:: HttpRequest
+
+    See :class:`django.http.HttpRequest`.
diff --git a/doc/flow.rst b/doc/flow.rst
@@ -295,132 +295,6 @@ For example, to grant permission to revise an answer on a
             - change_answer
     value: 1
 
-Predefined Page Types
----------------------
-
-.. currentmodule:: course.page
-
-The following page types are predefined:
-
-* :class:`Page` -- a page of static text
-* :class:`TextQuestion` -- a page allowing a textual answer
-* :class:`SurveyTextQuestion` -- a page allowing an ungraded textual answer
-* :class:`HumanGradedTextQuestion` -- a page allowing an textual answer graded by a human
-* :class:`InlineMultiQuestion` -- a page allowing answers to be given in-line of a block of text
-* :class:`ChoiceQuestion` -- a one-of-multiple-choice question
-* :class:`MultipleChoiceQuestion` -- a many-of-multiple-choice question
-* :class:`SurveyChoiceQuestion` -- a page allowing an ungraded multiple-choice answer
-* :class:`PythonCodeQuestion` -- an autograded code question
-* :class:`PythonCodeQuestionWithHumanTextFeedback`
-  -- a code question with automatic *and* human grading
-* :class:`FileUploadQuestion`
-  -- a question allowing a file upload and human grading
-
-.. warning::
-
-    If you change the type of a question, you *must* also change its ID.
-    Otherwise, RELATE will assume that existing answer data for this
-    question applies to the new question type, and will likely get very
-    confused, for one because the answer data found will not be of the
-    expected type.
-
-.. |id-page-attr| replace::
-
-    A short identifying name, unique within the page group. Alphanumeric
-    with underscores, no spaces.
-
-.. |title-page-attr| replace::
-
-    The page's title, a string. No markup allowed. Required. If not supplied,
-    the first ten lines of the page body are searched for a
-    Markdown heading (``# My title``) and this heading is used as a title.
-
-.. |access-rules-page-attr| replace::
-
-    Optional. See :ref:`page-permissions`.
-
-.. |value-page-attr| replace::
-
-    An integer or a floating point number, representing the
-    point value of the question.
-
-.. |is-optional-page-attr| replace::
-
-    Optional. A Boolean value indicating whether the page is an optional page
-    which does not require answer for full completion of the flow.  If
-    ``true``, the attribute *value* should not present. Defaults to ``false``
-    if not present.  Note that ``is_optional_page: true`` differs from ``value:
-    0`` in that finishing flows with unanswered page(s) with the latter will be
-    warned of "unanswered question(s)", while with the former won't. When using
-    not-for-grading page(s) to collect answers from students, it's to better
-    use ``value: 0``.
-
-.. |text-widget-page-attr| replace::
-
-    Optional.
-    One of ``text_input`` (default), ``textarea``, ``editor:MODE``
-    (where ``MODE`` is a valid language mode for the CodeMirror editor,
-    e.g. ``yaml``, or ``python`` or ``markdown``)
-
-Show a Page of Text/HTML (Ungraded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: Page()
-
-Fill-in-the-Blank (Automatically Graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: TextQuestion()
-
-Free-Answer Survey (Ungraded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: SurveyTextQuestion()
-
-Fill-in-the-Blank (long-/short-form) (Human-graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: HumanGradedTextQuestion()
-
-Fill-in-Multiple-Blanks (Automatically Graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: InlineMultiQuestion()
-
-One-out-of-Many Choice (Automatically Graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: ChoiceQuestion()
-
-Many-out-of-Many Choice (Automatically Graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: MultipleChoiceQuestion()
-
-One-out-of-Many Survey (Ungraded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: SurveyChoiceQuestion()
-
-Write Python Code (Automatically Graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: PythonCodeQuestion()
-
-Write Python Code (Automatically and Human-Graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. autoclass:: PythonCodeQuestionWithHumanTextFeedback()
-
-Upload a File (Human-Graded)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. autoclass:: FileUploadQuestion()
-
-Definining your own page types
-------------------------------
-
-.. autoclass:: PageContext
-.. autoclass:: PageBehavior
-.. autofunction:: get_auto_feedback
-.. autoclass:: AnswerFeedback
-.. autoclass:: PageBase
-
-.. currentmodule:: course.page.base
-.. autoclass:: PageBaseWithTitle
-.. autoclass:: PageBaseWithHumanTextFeedback
-.. autoclass:: PageBaseWithCorrectAnswer
-
 .. _flow-life-cycle:
 
 Life cycle
diff --git a/doc/index.rst b/doc/index.rst
@@ -37,9 +37,6 @@ features:
 * Facilitates live quizzes in the classroom.
 * In-class instant messaging via XMPP.
   Works well with `xmpp-popup <https://github.com/inducer/xmpp-popup>`_.
-* Built-in support for `VideoJS <http://www.videojs.com/>`_ offers
-  easy-to-use support for integrating HTML5 video into course content
-  without the need for third-party content hosting.
 
 RELATE is a based on the popular `Django <https://docs.djangoproject.com/>`_
 web framework for Python.  It lets students participate in online activities,
@@ -48,24 +45,17 @@ pages, each of which can be both static or interactive content, for exapmle a
 video, a quiz question, a page of text, or, within the confines of HTML,
 something completely different.
 
-Links
------
-
-More information around the web:
-
-* `Documentation <http://documen.tician.de/relate>`_
-* `Source code <https://github.com/inducer/relate>`_
-
 Table of Contents
 -----------------
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 2
 
     content
     flow
+    page-types
     api
-    page
+    flow-page-api
     faq
     misc
     🚀 Github <https://github.com/inducer/relate>
diff --git a/doc/page-types.rst b/doc/page-types.rst
