Fixed many formatting issues with the documentation.

Author: mrucker

doc/source/misc/_templates/base.rst doc/source/_templates/base.rst

@@ -37,7 +37,7 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["misc/_templates"]
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -55,7 +55,7 @@
 # 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 = [ "misc/_statics" ]
+html_static_path = [ ]
 
 html_theme_options = {
     #'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
@@ -94,9 +94,23 @@
 
 .. raw:: html
 
+    <style>
+        /*Make children of section and not (nbinput/nboutput) 
+        followed by (nbinput/nboutput) have24px padding. This 
+        is what the rtd_theme uses.*/
+        :is(section > :not(section):last-child,
+            section > :not(:is(
+                .nbinput:has (+ .nboutput, + .nbinput),
+                .nboutput:has(+ .nboutput, + .nbinput)
+            ))
+        ) {
+            margin-bottom: 24px !important 
+        }
+    </style>
+
     <div class="admonition note">
-      To view an interactive online version of this page
-      <a href="https://mybinder.org/v2/gh/vowpalWabbit/coba/{{ env.config.release|e }}?filepath={{ docname|e }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a> (takes time to initialize).
+      To interact with this Notebook:
+      <a href="https://mybinder.org/v2/gh/vowpalWabbit/coba/{{ env.config.release|e }}?filepath={{ docname|e }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>. To download this Notebook: <a href="{{ env.docname.split('/')|last|e + '.ipynb' }}" download>click here</a>.
     </div>
 """
 

doc/source/misc/_templates/class_with_ctor.rst doc/source/_templates/class_with_ctor.rst

@@ -244,11 +244,12 @@
    "source": [
     "### Environments From Local Supervised Datasets\n",
     "\n",
-    "Next we can incorporate new environments from local datasets. Coba has built-in support for the following formats:\n",
-    "* CSV\n",
-    "* ARFF (i.e., https://waikato.github.io/weka-wiki/formats_and_processing/arff_stable/)\n",
-    "* Libsvm (e.g., https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/multiclass.html)\n",
-    "* Manik (e.g., http://manikvarma.org/downloads/XC/XMLRepository.html)\n",
+    "Next we can incorporate new environments from local datasets in the following formats:\n",
+    "\n",
+    "+ CSV\n",
+    "+ ARFF (i.e., https://waikato.github.io/weka-wiki/formats_and_processing/arff_stable/)\n",
+    "+ Libsvm (e.g., https://www.csie.ntu.edu.tw/~cjlin/libsvmtools/datasets/multiclass.html)\n",
+    "+ Manik (e.g., http://manikvarma.org/downloads/XC/XMLRepository.html)\n",
     "\n",
     "For example, we may have the iris dataset saved in `iris.arff` in the arff format. To create an environment from this dataset we can."
    ]
@@ -287,11 +288,12 @@
    "source": [
     "### Environments From Synthetic Datasets\n",
     "\n",
-    "Coba provides access to several synthetic data generators from many function class families. Coba has built-in support for the following formats:\n",
-    "* Linear -- `cb.Environments.from_linear_synthetic`\n",
-    "* Nearest Neighbors -- `cb.Environments.from_neighbors_synthetic`\n",
-    "* Kernel Methods -- `cb.Environments.from_kernel_synthetic`\n",
-    "* Multilayer Perceptrons -- `cb.Environments.from_mlp_synthetic`\n",
+    "Coba provides access to several synthetic data generators from many function class:\n",
+    "\n",
+    "+ Linear -- `cb.Environments.from_linear_synthetic`\n",
+    "+ Nearest Neighbors -- `cb.Environments.from_neighbors_synthetic`\n",
+    "+ Kernel Methods -- `cb.Environments.from_kernel_synthetic`\n",
+    "+ Multilayer Perceptrons -- `cb.Environments.from_mlp_synthetic`\n",
     "\n",
     "For example, below we create a synthetic dataset whose expected reward function is linear with respect to action features:"
    ]
@@ -704,7 +706,7 @@
    "source": [
     "### Filters that apply to rewards\n",
     "\n",
-    "1. binary -- Turn rewards into 1/0 with max reward being 1 and all other 0."
+    "1. `binary` -- Turn rewards into 1/0 with max reward being 1 and all other 0."
    ]
   },
   {

doc/source/misc/_templates/class_with_ctor2.rst doc/source/_templates/class_with_ctor2.rst

@@ -449,9 +449,10 @@
    "source": [
     "## Built-in Evaluators\n",
     "Coba comes with three built-in evaluators:\n",
-    "1. SequentialCB -- the default evaluator, it can perform on-policy and off-policy learning/evaluation for Learners\n",
-    "2. RejectionCB -- unbiased estimation of of exploration algorithm performance using logged interactions\n",
-    "3. SequentialIGL -- evaluation for interaction grounded learning algorithms with both feedback and rewards"
+    "\n",
+    "1. SequentialCB -- sequential on/off-policy learning/evaluation (default evaluator)\n",
+    "2. RejectionCB -- sequential on-policy learning/evaluation using logged data\n",
+    "3. SequentialIGL -- sequential interaction grounded learning/evaluation"
    ]
   },
   {

doc/source/misc/_templates/empty.rst doc/source/_templates/empty.rst

@@ -56,34 +56,34 @@
     "   ```python\n",
     "   1 or 'a' or None\n",
     "   ```\n",
-    "   <br>\n",
     "2. Dense sequences of values such as:\n",
     "   ```python\n",
     "   [1,2,3] or ['a',1,'b'] or (1,2,3)\n",
     "   ```\n",
-    "   <br>\n",
     "3. Sparse mappings of values (where missing values are assumed to be 0):\n",
     "   ```python\n",
     "   {1:2, 'a':3}\n",
     "   ```\n",
     "\n",
     "A few more notes:\n",
+    "\n",
     "* Individual values and dense values with strings can be thought of as sparse collections. That is,\n",
     "  ```python\n",
     "  [1,'a',5.2] ~= {0:1, 'a':1, 2:5.2}\n",
     "  ```\n",
-    "  <br>\n",
     "* Coba learners that support feature interactions assume 'x' is context features and 'a' is action features. So,\n",
     "  ```python\n",
     "  #Given given context ['a','b'] and action 'c' learner features 'x xx xa' would use as features\n",
     "  ['a', 'b'] + ['aa', 'ab', 'bb'] + ['ac','bc']\n",
     "  ```\n",
-    "  <br>\n",
     "* An easy trap to fall into is using numerical features when what is wanted are one-hot or string features\n",
     "  ```python\n",
-    "  {'actions':[1,2,3]}                   #Three actions with one continuous feature. This can cause high-correlation among action rewards.\n",
-    "  {'actions':[(1,0,0),(0,1,0),(0,0,1)]} #Three actions with disjoint features. Actions have independent predictions.\n",
-    "  {'actions':['1','2','3']}             #Equivalent to one-hot-encoding based on ['1','2','3'] ~= [{'1':1},{'2':1},{'3':1}]\n",
+    "  #Three actions with one continuous feature. This can cause high-correlation among action rewards.\n",
+    "  {'actions':[1,2,3]}\n",
+    "  #Three actions with disjoint features. Actions have independent predictions.\n",
+    "  {'actions':[(1,0,0),(0,1,0),(0,0,1)]}\n",
+    "  #Equivalent to one-hot-encoding based on ['1','2','3'] ~= [{'1':1},{'2':1},{'3':1}]\n",
+    "  {'actions':['1','2','3']}\n",
     "  ```"
    ]
   },

doc/source/conf.py

@@ -6,14 +6,18 @@
    "metadata": {},
    "source": [
     "# Results\n",
-    "The **Result** class the outcome of an **Experiment**. It has several features to support easy analysis. In this notebook we will learn:\n",
-    "1. **Result Creation**: How to create a Result from an Experiment.\n",
-    "2. **Result Plotting**: How to create plots of the learners that were evaluted by an experiment\n",
-    "3. **Result Loading**: How to load results from disk\n",
-    "4. **Result Filtering**: How to use filtering to create custom plots from a large experiment result \n",
-    "5. **Result to Pandas**: How to turn Result into a collection of Pandas dataframes for more in-depth analysis\n",
     "\n",
-    "## Creation\n",
+    "A **Result** is the outcome of an **Experiment**. It has several features to support easy analysis. \n",
+    "\n",
+    "In this notebook we will learn about **Result**...\n",
+    "\n",
+    "1. ...Creating: How to create a Result from an Experiment\n",
+    "2. ...Plotting: How to create plots from a Result\n",
+    "3. ...Loading: How to load Result from disk\n",
+    "4. ...Selecting: How to select which Result data to analyze\n",
+    "5. ...Pandas: How to turn Result into Panda Dataframes\n",
+    "\n",
+    "## Creating\n",
     "\n",
     "**Results** are created by running an Experiment. Below is a simple example of this:"
    ]
@@ -189,9 +193,9 @@
    "id": "c470df2f",
    "metadata": {},
    "source": [
-    "### Filtering to Finished Environments\n",
+    "### Selecting Finished Environments\n",
     "\n",
-    "One particularly useful feature is looking at the results of an experiment while it runs (this can be done by loading an Experiment restoration file at any time while the experiment is running). When doing this it is useful to filter the results down to just the Environments that have been fully processed. Otherwise some learners may look better or worse simply because they have been evaluated against a particularly easy/hard environment. Filtering to just finished environments looks like this."
+    "One particularly useful feature is looking at the results of an experiment while it runs (this can be done by loading an a Result from experiment logs while the experiment is running). When doing this it is useful to select just the Environments that have been fully processed. If we didn't some learners may look better or worse simply because of missing or extra data. Selecting down to only finished environments looks like this."
    ]
   },
   {
@@ -220,9 +224,9 @@
    "id": "3b9f2d3f",
    "metadata": {},
    "source": [
-    "### Filtering In General\n",
+    "### Selecting In General\n",
     "\n",
-    "When running very large experiments it can often be useful to filter down to specific learners or environments. This can be done using the `where` method. Below is an example where we filter down to just the vw learner. When using strings it will perform a regex match so this can be very powerful."
+    "When running very large experiments it can often be useful to select down to specific learners or environments to answer questions. This can be done using the `where` method. Below is an example where we select down to just the vw learner. When selecting on strings Coba will perform a regex match so this can be very powerful."
    ]
   },
   {