From cc2afb1e142974bfaeab95d0e14ccef1af885d13 Mon Sep 17 00:00:00 2001 From: DaveParillo Date: Tue, 5 Jun 2018 21:29:36 -0700 Subject: [PATCH 1/2] Fixes #20, a few minor typos, and addresses the TODO in the activecode langauges option --- source/directives.rst | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/source/directives.rst b/source/directives.rst index b049211..f4a982d 100644 --- a/source/directives.rst +++ b/source/directives.rst @@ -41,7 +41,8 @@ General Syntax All directives start out with ``..``, then a single space, followed by the name of the directive (e.g. ``video``, as seen below), and then ``::``, followed by a single space. -Most directives have a required argument of a unique identifier, which goes immediately to the right of the directive name. This is for logging purposes. It's also necessary for managing any controls or +Most directives have a required argument of a unique identifier, which goes immediately to the right of the directive name. +This unique identifier is used for logging, managing controls, and for testing Runestone components. Spacing, including indentation consistency, is very important in implementing directives inside ``.rst`` files. Any missed or incorrect space may cause unexpected errors, strange-looking pages, or may cause information not to display on the deployed pages in your online book, so it's worth checking your final product before releasing content to students. @@ -53,6 +54,9 @@ When reStructured Text files are *built* into static files in your Runestone tex We are in the process of creating a full set of documentation for the HTML and JavaScript created by our special Runestone directives. +Runestone is a `Sphinx `_ extension. +That means directives you can use in Sphinx will also work in Runestone. + Directives ---------- @@ -211,7 +215,7 @@ This unique identifer will be the ``div`` id that contains this particular code ``:caption:`` If used, this requires a text parameter. The text parameter to this argument is formatted as a caption, underneath the activecode block. You can see one in the example above, where the caption is ``A Turtle making a square``. -``:language:`` The text argument to this parameter can be python, javascript, or html. TODO TODO is this still true, and what is the default if you leave it off, is it Python? +``:language:`` The text argument to this parameter can be python, python3, java, C, C++, ruby, javascript, or html. The default language is Python 2. Languages other than python, javascript, and html require an external server. ``:include:`` This option allows you to prepend other code blocks to this activecode block. It is useful because it allows you to write individual activecode examples that build on each other without having to duplicate all the code and force the user to scroll through the code to find the newly introduced content. For example, if you write a function definition in one activecode block, you can include that block in a later activecode block using the ``:include:`` argument, and thus can invoke that function in the current activecode block without redefining it. This argument requires at least one, and can take multiple, parameters: the unique identifiers of the activecode blocks that you want to include. (See the examples in reStructured text for an example of how you can use this.) @@ -241,9 +245,13 @@ A tool has been developed to easily record and create the directive syntax for a **Developer Notes** -Each activecode window is running in the browser. There is no need to connect to a server, or to even be online, for these examples to work. The activecode directive makes use of **Skulpt** (``www.skulpt.org``), which is an open source javascript implementation of Python. +The default activecode language (python) runs directly in the browser. +There is no need to connect to a server, or to even be online, for these examples to work. +The activecode directive makes use of **Skulpt** (``www.skulpt.org``), +which is an open source javascript implementation of Python. +Other activecode languages require access to an external server to compile code on behalf of activecode. -Normally an output from a print statment is appended to a ``
`` element in the web page.  Graphical output, such as the turtle graphics program in the example, is done on a ````.
+Normally an output from a print statement is appended to a ``
`` element in the web page.  Graphical output, such as the turtle graphics program in the example, is done on a ````.
 
 **Logs & Grading**
 
@@ -749,12 +757,12 @@ but it cannot have less.
 
 **Optional Arguments**
 
-``casei``  -- Perform case insensitive comparisons between values provided in ``blank`` fields and answer fields.
+``casei``  - Perform case insensitive comparisons between values provided in ``blank`` fields and answer fields.
 
 Parsons Problems
 ~~~~~~~~~~~~~~~~~
 
-The Parsons Problem directive, ``..parsonsprob::``, allows for insertion of a 2D Parsons problem. In a Parsons problem, users are provided with the lines / blocks of code (in the left source area) needed to solve a problem and are asked to reorder them to create a solution (in the right answer area). The 2D version further asks users to specify how much to indent the code. This is semantically meaningful in Python and good code practice in other programming languages. In the problem below, the third line needs to be indented to be correct.
+The Parsons Problem directive, ``.. parsonsprob::``, allows for insertion of a 2D Parsons problem. In a Parsons problem, users are provided with the lines / blocks of code (in the left source area) needed to solve a problem and are asked to reorder them to create a solution (in the right answer area). The 2D version further asks users to specify how much to indent the code. This is semantically meaningful in Python and good code practice in other programming languages. In the problem below, the third line needs to be indented to be correct.
 
 ::
 
@@ -780,11 +788,13 @@ The identifier after the ``::`` must be unique. No spaces.
 
 **Optional Arguments**
 
-``:language:`` - You can specify the language for the code. *python* is the default value, but other programming languages are possible: *java*, *javascript*, *html*, *c*, *c++*, or *ruby*. In addition to these programming languages, you can also specify *natural* for plain text.
+``:adaptive:`` - If specified, then this option will offer help after a few failed attempts.  After more failures, it will incrementally simplify the problem.
+
+``:language:`` - You can specify the language for the code. *python* is the default value, but other programming languages are possible: *java*, *javascript*, *html*, *c*, *c++*, or *ruby*. In addition to these programming languages, you can also specify *natural* for plain text. The default language can be set in the book ``pavement.py`` file.
 
 ``:noindent:`` - If you do not want to use the 2D capability, this argument will indent blocks as you specify them (see below). This makes the problem significantly easier to solve.
 
-``:maxdist:`` - If you specify distractors in the code, then this will specify the maximum number that are presented to the user.
+``:maxdist:`` - If you specify distractors in the code, then this will specify the maximum number of distractors presented to the user.
 
 ``:order:`` - If you don't want the code to be randomly shuffled, you can specify the order of the blocks in a comma-separated list (e.g., 0,5,3,2,4,1).
 
@@ -807,9 +817,9 @@ Place the question text after the arguments. Use ``-----`` to separate the quest
     	  curmax = alist[0]
     	  for item in alist:
        =====
-    		 if item > curmax:
+    		 if item > curmax:
        =====
-             if item < curmax: #paired
+             if item > curmax: #paired
        =====
     			curmax = item
        =====

From abc2d5708ba63d3e481b6538c049cdc055967a0f Mon Sep 17 00:00:00 2001
From: DaveParillo 
Date: Wed, 6 Jun 2018 20:10:17 -0700
Subject: [PATCH 2/2] Fixed #26 by making links anonymous.  Removed duplicate
 sentence in developer.rst.  Minor updates.

---
 source/developer.rst | 81 ++++++++++++++++++++++++++++++++++----------
 source/intro.rst     |  5 +--
 2 files changed, 67 insertions(+), 19 deletions(-)

diff --git a/source/developer.rst b/source/developer.rst
index 3bc8723..6f170b8 100644
--- a/source/developer.rst
+++ b/source/developer.rst
@@ -1,31 +1,68 @@
 Developer Documentation for Runestone Interactive Tools
 =======================================================
 
-The Runestone system uses reStructuredText (.rst) as its primary markup language.  reStructuredText is easy to read in plain text form, and can be transformed into html, latex, epub, or our own interactive book format.
-
-We do our development on Linux and OS X.  We use standard Unix commands that may not exist on Windows.  If you want to install on Windows, you may need to install the Cygwin tools and do your work in that environment.
+The Runestone system uses `ReStructured Text `__ (.rst) as its primary markup language.
+ReStructuredText is easy to read in plain text form, and can be transformed into 
+html, latex, epub, or our own interactive book format.
+Runestone is built on top of `Sphinx `__,
+so any markup valid in `ReStructured Text `__ 
+or `Sphinx `__
+is also valid in Runestone.
 
 
 Important Notes
 ---------------
 
-1.  We do our development on Linux and OS X.  We use standard Unix commands that may not exist on Windows.  If you want to install on Windows, you may need to install the Cygwin tools and do your work in that environment.
-
-Development Parts
------------------
-
-If you plan to develop on the Runestone project, you should know that there are now **three pieces** of a **local Runestone development environment.**
+- We do our development on Linux and OS X.
+  We use standard Unix commands that may not exist on Windows.
+  If you want to install on Windows, you may need to install the
+  Cygwin tools and do your work in that environment.
 
-1. The `Runestone Components `_ - this is the development version of the library you get when you ``pip install runestone``. *You should examine this first.* See the GitHub repository `HERE `_, where the README is approximately up to date. If you are *only* interested in authoring content and/or developing directives (extensions to reStructuredText that provide interactive components of textbooks), you only need this. (You may also want open source book content to edit -- see #3. You can skip #2.)
+- Books should compile easily on any environment where sphinx installs and runs.
 
-2. The `Runestone Server `_ - this is the application that goes inside a **web2py** server. If you plan to run your own server for an interactive textbook, or develop on the Runestone server, you should install this. See the GitHub repository `HERE `_, where the README is approximately up to date.
+- Developers who desire to add new components to Runestone, or
+  modify the Runestone server, should consider developing on Ubuntu 16.10.
+  Tests that run within the Selenium test automation framework should
+  *theoretically* run anywhere it installs, however, some 
+  versions appear to be more forgiving than others.
 
-3. **A book** written for the runestone environment to build, deploy, and then serve on your local server. Typically, a book repository will be cloned (and potentially edited) to the appropriate place inside the  Runestone Server application, and can be built using the tools provided by RunestoneComponents. You can see an example of a book created for the Runestone environment on GitHub `HERE `_. See the Runestone Components README for how to build and serve the book content locally.
-
-Note that if you intend *solely* to be a content author and *not* to do any code development for the Runestone project, you should look at the RunestoneComponents repository only.
-
-`HERE `_ you can see every GitHub repository managed by RunestoneInteractive.
+Development Parts
+-----------------
 
+If you plan to develop on the Runestone project,
+you should know that there are now **three pieces** of a **local Runestone development environment.**
+
+1. The `Runestone Components `_ -
+   this is the development version of the library you get when you ``pip install runestone``.
+   *You should examine this first.*
+   See the `components GitHub repository `__,
+   where the README is approximately up to date.
+   If you are *only* interested in authoring content and/or developing directives
+   (extensions to ReStructuredText that provide interactive components of textbooks), you only need this.
+   (You may also want open source book content to edit -- see #3. You can skip #2.)
+
+2. The `Runestone Server `_ -
+   this is the application that goes inside a **web2py** server.
+   If you plan to run your own server for an interactive textbook,
+   or develop on the Runestone server, you should install this.
+   See the `server GitHub repository `__,
+   where the README is approximately up to date.
+
+3. **A book** written for the runestone environment to build, deploy, and then serve on your local server.
+   Typically, a book repository will be cloned (and potentially edited) 
+   to the appropriate place inside the Runestone server application, 
+   and can be built using the tools provided by RunestoneComponents. 
+   You can see an example of a book created for the Runestone environment on 
+   GitHub `here `_. 
+   See the `RunestoneComponents README `__
+   for how to build and serve the book content locally.
+
+Note that if you intend *solely* to be a content author and *not* to do any 
+code development for the Runestone project, 
+you should look at the RunestoneComponents repository only.
+
+The `Runestone organization `_ 
+on Github provides access to every GitHub repository managed by RunestoneInteractive.
 
 **NOTE: This documentation is currently undergoing significant updates. If you wish to develop on the Runestone project, please see the above links.**
 
@@ -33,10 +70,20 @@ Note that if you intend *solely* to be a content author and *not* to do any code
 Using Special Runestone Extensions
 ----------------------------------
 
-Runestone includes all of the pre-existing `ReStructured Text `_ formatting -- you can use the documentation at that link for writing up book content, to include formatting like **bold** or *italic* or hyperlinks, etc. Runestone also has several particular **directives**, which are certain syntaxes that allow you to include special interactive elements in a page. These include video, images, running and saving interactive code in the browser, and different types of exercises such as multiple choice problems and fill in the blank questions. The Runestone directives documentation includes full documentation of all of the available Runestone directives, including:
+Runestone includes all of the pre-existing `ReStructured Text `__ 
+formatting -- you can use the documentation there for syntax guidance, 
+for example: formatting like **bold** or *italic*, adding hyperlinks, tables, figures, formulas, etc. 
+Runestone extends `Sphinx `__ with several custom 
+ReStructured Text *directives*. 
+**Directives** allow you to include special interactive elements in a page.
+Runestone directives include video, images, working with source code in the browser, 
+adding interactive exercises, and more.
+The Runestone directives documentation includes full documentation of all of the available Runestone directives,
+including:
 
 * What each directive allows you to create
 * The syntax for using each directive
 * Examples, or links to examples, of how instructors have used these directives in interactive textbook work
 * If applicable, how exercises created by these directives can be graded
 * Available additional developer documentation for each directive
+
diff --git a/source/intro.rst b/source/intro.rst
index 9535413..5c4f685 100644
--- a/source/intro.rst
+++ b/source/intro.rst
@@ -51,7 +51,7 @@ This three step process may seem complicated but it provides a lot of flexibilit
 
 The best thing is, you don't have to write an entire book to take advantage of the interactive tools.  You can use Runestone to make lecture demonstrations, or set up labs or short tutorials for your students.  If you do that you can even host them on your own computer very easily.
 
-Full documentation for all of the Runestone Components can be found at `The Runestone Home `_   If you have a suggestion for a new interactive component, or would like to help with the development and documentation of the Runestone Components please visit our page on `Github `_. If you would like to help out with any of the books they are all freely available `on github `_.
+Full documentation for all of the Runestone Components can be found at `The Runestone Home `_   If you have a suggestion for a new interactive component, or would like to help with the development and documentation of the Runestone Components please visit our page on `Github `__. If you would like to help out with any of the books they are all freely available `on github `__.
 
 The Runestone Server
 --------------------
@@ -62,4 +62,5 @@ However there are a handful of others out there who for whatever reason, privacy
 
 The Runestone Server is built on top of the `web2py `_ application framework.  I know, you've never heard of web2py, why would I do such a thing?  In 2011 it seemed like the right choice.  If I were starting again today it would definitely be a `Flask `_ application.  I still hope to port everything to Flask one day.  But when I think about the opportunity cost of taking an entire summer to port the code versus using the summer to add new features to what is there, I lean heavily towards the new thing.  Eventually all of the bad decisions and shortcuts I've taken over the years will force me to do a rewrite.
 
-If you're still with me, and are interested in helping out with server check out our `Github `_ page, in particular have a look at the CONTRIBUTING document.
+If you're still with me, and are interested in helping out with server check out our `Github `__ page, in particular have a look at the CONTRIBUTING document.
+