Docs: Rewrite for CodeChat.

Author: bjones1

conf.py

@@ -176,12 +176,14 @@
     "*.css": "CSS",
     "*.js": "JavaScript",
     "*.html": "HTML",
-    # Perl use # for comments, so pretend these files are Perl.
+    # Perl uses ``#`` for comments, so pretend these files are Perl.
     "*.in": "Perl",
     ".gitignore": "Perl",
     "*.cfg": "INI",
-    # This is actually a Python file.
+    # These are actually a Python files.
     "codechat_config.json": "Python",
+    "conf.tmpl": "Python",
+    "pavement.tmpl": "Python",
 }
 #
 # **CodeChat note::** This is a list of exclude_patterns_ which applies only to

runestone/accessibility/__init__.py

@@ -1,4 +1,4 @@
-# *********
-# |docname|
-# *********
+# ************************************
+# |docname| - the accessibility module
+# ************************************
 from .accessibility import *

runestone/accessibility/accessibility.py

@@ -1,42 +1,36 @@
 """
-*********
-|docname|
-*********
-
-This extension adds an accessibiligy stylesheet.
-
-By the 'accessibility_style' config value (in conf.py of
+**********************************************
+|docname| - select an accessibility stylesheet
+**********************************************
+By setting the `accessibility_style` config value (in `conf.py <../common/project_template/conf.tmpl>` of
 an interactive book project) you can select what accessibility stylesheet
-you want to add ('normal', 'light', 'darkest' or 'none')
+you want to add (``normal``, ``light``, ``darkest``, or ``none``).
 
-An accessibility stylesheet overs:
+An accessibility stylesheet covers:
 
--Change of nav bar to color code based on Users using either mouse or
-keyboard to navigate the menu
--Adjusting bootstrap buttons to invert color on active and on focus for
-accessibility for users
--Changing default bootstrap buttons to follow WCAG 2.0 guidlines
+-   Change of nav bar to color code based on Users using either mouse or keyboard to navigate the menu
+-   Adjusting bootstrap buttons to invert color on active and on focus for accessibility for users
+-   Changing default bootstrap buttons to follow WCAG 2.0 guidelines
 
-acessibility.css reflects WCAG 2.0 AA compliance
-acessibilitydarkest.css reflects WCAG 2.0 AAA compliance
-accessibilitylight.css doesn't change bootstrap colors but adds
-inversion
+| ``acessibility.css`` reflects WCAG 2.0 AA compliance
+| ``acessibilitydarkest.css`` reflects WCAG 2.0 AAA compliance
+| ``accessibilitylight.css`` doesn't change bootstrap colors but adds inversion
 
-Personally we prefered WCAG 2.0 AA compliance, so accessibility.css
+Personally we prefered WCAG 2.0 AA compliance, so ``accessibility.css``
 reflects ideal changes
 
-http://imgur.com/a/TSDNf
-This shows the different CSS files from most compliance (left) to least
-compliance (right)
+.. figure:: https://i.imgur.com/jFzkI6g.jpg
+
+    This shows the different CSS files from most compliance (left) to least compliance (right).
 """
 
 
 def setup(app):
     app.add_config_value("accessibility_style", "normal", "html")
 
-    # Since the `init_values()` method of the `app.config` object (Config class)
+    # Since the ``init_values()`` method of the ``app.config`` object (Config class)
     # is not invoked yet (will be invoked after the setup of all extensions),
-    # we need to access the raw config dictionary here
+    # we need to access the raw config dictionary here.
     acc_style = app.config._raw_config.get("accessibility_style", "normal")
 
     if acc_style == "normal":

runestone/accessibility/css/accessibility.css

@@ -1,7 +1,7 @@
 /*
-*********
-|docname|
-*********
+**********************************************
+|docname| - a WCAG 2.0 AA compliant stylesheet
+**********************************************
 */
 
 /* Variables holding theme colors */

runestone/accessibility/css/accessibilitydarkest.css

@@ -1,7 +1,7 @@
 /*
-*********
-|docname|
-*********
+***********************************************************
+|docname| - a WCAG 2.0 AAA compliant stylesheet (dark mode)
+***********************************************************
 */
 
 /*Navigation Tabbing Styling*/

runestone/accessibility/css/accessibilitylight.css

@@ -1,7 +1,7 @@
 /*
-*********
-|docname|
-*********
+********************************************************************************
+|docname| - a stylesheet that doesn't change bootstrap colors but adds inversion
+********************************************************************************
 */
 
 /*Navigation Tabbing Styling*/

runestone/common/project_template/conf.tmpl

@@ -1,4 +1,6 @@
-# -*- coding: utf-8 -*-
+# *************************************************************
+# |docname| - Sphinx configuration file for a Runestone project
+# *************************************************************
 #
 # Problem Solving with Algorithms and Data Structures documentation build configuration file, created by
 # sphinx-quickstart on Thu Oct 27 08:17:45 2011.
@@ -276,9 +278,13 @@ html_show_sourcelink = False
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'PythonCoursewareProjectdoc'
 
-# 'accessibility_style' config value is defined in the 'accessibility' extension.
+# .. _accessibility_style:
+#
+# accessibility_style
+# -------------------
+# This config value is defined in the `../../accessibility/accessibility.py` extension.
 # By this config value you can select what accessibility stylesheet
-# you want to add ('normal', 'light', 'darkest' or 'none')
+# you want to add (``normal``, ``light``, ``darkest`` or ``none``).
 #accessibility_style = 'normal'
 
 # Config values for specific Runestone components

runestone/overview.rst

@@ -27,7 +27,6 @@ Base Class Provides
 
 All Components
 --------------
-
 * constructor that takes an object of options
 * restoreAnswers
 * setLocalStorage