initial rewriting of docs

Author: tulga-rdn

docs/src/check.ipynb

@@ -9,11 +9,14 @@
     "slideshow": {
      "slide_type": ""
     },
-    "tags": []
+    "tags": [],
+    "vscode": {
+     "languageId": "raw"
+    }
    },
    "source": [
     ".. important::\n",
-    "   Jupyter widgets cannot be run within in documentation. To be able to interact with the widget you must run a mybinder instance. To run a mybinder instance of this notebook please use this link https://mybinder.org/v2/gh/osscar-org/scicode-widgets/HEAD?labpath=docs%2Fsrc%2Fexercises.ipynb."
+    "   Jupyter widgets cannot be run within the documentation. To interact with the widget, you must run a mybinder instance. To run a mybinder instance of this notebook, please use this link https://mybinder.org/v2/gh/osscar-org/scicode-widgets/HEAD?labpath=docs%2Fsrc%2Fcheck.ipynb."
    ]
   },
   {
@@ -29,7 +32,7 @@
    "id": "2",
    "metadata": {},
    "source": [
-    "Checks intention is to give students a way to validate their code solution. The student's code can be validated by providing a list of inputs and references comparing the output of the student's code with the references, or by directy testing certain functional behavior of the code. In cases when reference outputs need to be obfuscated the outputs that are compared can be passed through a _fingerprint_ function. This notebook goes through each of these features and presents an example."
+    "The purpose of a check is to give students a way to validate their code solutions. The student's code can be validated by providing a list of inputs and references, which are compared to the output of the student's code, or by directly testing certain functional behavior of the code. In cases when reference outputs need to be obfuscated, the outputs that are compared can be passed through a _fingerprint_ function. This notebook goes through each of these features and presents an example."
    ]
   },
   {
@@ -51,7 +54,7 @@
    "id": "4",
    "metadata": {},
    "source": [
-    "Similar as for the `ExerciseRegistry` we need to define a `CheckRegistry` that registers the checks for each exercise."
+    "Similar to the `ExerciseRegistry`, we need to define a `CheckRegistry` that registers the checks for each exercise."
    ]
   },
   {
@@ -89,7 +92,7 @@
     "\n",
     "\n",
     "check_code_ex = CodeExercise(\n",
-    "    key=\"sinus_with_references_1\",\n",
+    "    key=\"sine_with_references_1\",\n",
     "    code=sin,\n",
     "    check_registry=check_registry,\n",
     ")\n",
@@ -121,7 +124,7 @@
    "id": "8",
    "metadata": {},
    "source": [
-    "Because there are asserts that are repeatedly needed for almost any kind of exercise, we provide of a set of asserts"
+    "Since some asserts are frequently needed across various exercises, we provide a common set of asserts."
    ]
   },
   {
@@ -139,14 +142,14 @@
     "    assert_type,\n",
     ")\n",
     "\n",
-    "def sinus(arr):\n",
+    "def sine(arr):\n",
     "    import numpy as np\n",
     "    return np.cos(arr) # oops! wrong solution\n",
     "\n",
     "check_code_ex = CodeExercise(\n",
-    "    key=\"sinus_with_references_2\",\n",
-    "    title=\"sinus\",\n",
-    "    code=sinus,\n",
+    "    key=\"sine_with_references_2\",\n",
+    "    title=\"sine\",\n",
+    "    code=sine,\n",
     "    check_registry=check_registry,\n",
     ")\n",
     "\n",
@@ -216,13 +219,13 @@
    },
    "outputs": [],
    "source": [
-    "def sinus(arr):\n",
+    "def sine(arr):\n",
     "    import numpy as np\n",
     "    return np.cos(arr) # oops! wrong solution\n",
     "\n",
     "code_ex_functional_behavior = CodeExercise(\n",
-    "    key=\"sinus_functional_behavior\",\n",
-    "    code=sinus,\n",
+    "    key=\"sine_functional_behavior\",\n",
+    "    code=sine,\n",
     "    check_registry=check_registry,\n",
     ")\n",
     "\n",
@@ -250,7 +253,7 @@
     "tags": []
    },
    "source": [
-    "## Obfuscating the reference solution with fingerprint"
+    "## Obfuscating the reference solution with a fingerprint"
    ]
   },
   {
@@ -272,19 +275,19 @@
     "    \n",
     "    What has wings but in the air it not swings.\n",
     "    I looked to the north, but it was not worth.\n",
-    "    What I am looking for?\n",
+    "    What am I looking for?\n",
     "    \"\"\"\n",
     "    return \"\"\n",
-    "code_input_sinus = CodeInput(riddle)\n",
+    "code_input_sine = CodeInput(riddle)\n",
     "\n",
     "check_code_ex = CodeExercise(\n",
     "    key=\"riddle\",\n",
-    "    code=code_input_sinus,\n",
+    "    code=code_input_sine,\n",
     "    check_registry=check_registry,\n",
     ")\n",
     "\n",
     "#def assert_equal(output, reference):\n",
-    "#    return \"\" if output == reference else \"Not correct solution. Hint: it is an animal in the antarctica.\"\n",
+    "#    return \"\" if output == reference else \"Not correct solution. Hint: it is an animal in the Antarctica.\"\n",
     "\n",
     "char_to_num = {char: num for num, char in enumerate(\"abcdefghijklmnopqrmnstuvwxyz\")}\n",
     "def string_to_int(output):\n",
@@ -318,7 +321,7 @@
    "id": "18",
    "metadata": {},
    "source": [
-    "The check registry also provides the possibility to check all the widgets. "
+    "The check registry also allows checking of all the widgets simultaneously. "
    ]
   },
   {
@@ -338,7 +341,7 @@
    "id": "20",
    "metadata": {},
    "source": [
-    "For the demo to automatically we simulate a button press using the private function that should not be used"
+    "For the demo, we simulate a button press using the private function that should not be used"
    ]
   },
   {

docs/src/developers.rst

@@ -1,12 +1,12 @@
 Developers
 ==========
 
-This is an instruction of the developer tools that help you contributing.
+This is an instruction of the developer tools that help you contribute.
 
 Running tests
 -------------
 
-Tests can be with run using
+Tests can be run by using
 
 .. code-block:: bash
 
@@ -21,25 +21,24 @@ You can source the test environment of tox after a run using
 Converting notebook test files
 ##############################
 
-The we store the notebooks as converted Python file using `jupytext` for the conversion
-for better versioning
+We store the notebooks as converted Python file using `jupytext` for better versioning
 
 .. code-block:: bash
 
   jupytext tests/notebooks/*.py --to ipynb
 
-Be aware that when runnng the tests with tox all `*.ipynb` are overwriten by their
-corresponding `*.py` file. For example, the file `test_widget_cue_box.ipynb` is
+Be aware that when running the tests with tox all `*.ipynb` are overwritten by the
+corresponding `*.py` files. For example, the file `test_widget_cue_box.ipynb` is
 overwritten by the conversion of `test_widget_cue_box.py` when running the test.
 
 
 Running in browser
 ##################
 
 We use selenium to test the widgets on user actions (like a button click). To run it in
-in the CI where no display is available. We run the browsers in headless model to not
-load the UI. For debugging a test however, it is often benificial to see what is
-happening in the window. To run the tests with the browser UI please use
+the CI where no display is available. We run the browsers in the headless mode to not
+load the UI. For debugging a test, however, it is often beneficial to see what is
+happening in the window. To run the tests with the browser UI, please use
 
 .. code-block:: bash
 
@@ -48,15 +47,16 @@ happening in the window. To run the tests with the browser UI please use
 Port issues
 ###########
 
-For the notebook server we fixed the port to 8815, if this port is not available you .
-It can happen that notebook process is not properly killed and remains as zombie
-process. You can check if a notebook with this port is already running using
+For the notebook server, we fixed the port to 8815. If this port is not available, you 
+you need to choose a different one. It can happen that notebook process is not properly
+killed and remains as zombie process. You can check if a notebook with the 8815 port
+is already running using
 
 .. code-block:: bash
     
    jupyter notebook list | grep 8815
 
-or if some process is using it 
+or if some other process is using it 
 
 .. code-block:: bash
 
@@ -88,7 +88,7 @@ To build the docs please use
 
    tox -e docs
 
-To open the doc with for example firefox you can run
+To open the documentation with Firefox, for example, you can run:
 
 .. code-block:: bash
 

docs/src/exercises.ipynb

@@ -9,11 +9,14 @@
     "slideshow": {
      "slide_type": ""
     },
-    "tags": []
+    "tags": [],
+    "vscode": {
+     "languageId": "raw"
+    }
    },
    "source": [
     ".. important::\n",
-    "   Jupyter widgets cannot be run within in documentation. To be able to interact with the widget you must run a mybinder instance. To run a mybinder instance of this notebook please use this link https://mybinder.org/v2/gh/osscar-org/scicode-widgets/HEAD?labpath=docs%2Fsrc%2Fexercises.ipynb."
+    "   Jupyter widgets cannot be run within the documentation. To interact with the widget, you must run a mybinder instance. To run a mybinder instance of this notebook, please use this link https://mybinder.org/v2/gh/osscar-org/scicode-widgets/HEAD?labpath=docs%2Fsrc%2Fexercises.ipynb."
    ]
   },
   {
@@ -72,7 +75,7 @@
    "id": "5",
    "metadata": {},
    "source": [
-    "Due to limitations of jupyter notebooks in saving the widgets state, we store and load the widget state by ourself using the `ExerciseRegstry`. It allows you specify a filename for the json file to store all the answers to all registered exercises. The exercises are registered by passing the `ExerciseRegstry` instance as input argument."
+    "Due to limitations of jupyter notebooks in saving the widgets state, we store and load the widget state by ourselves using the `ExerciseRegistry`. It allows you specify a filename for the JSON file to store all the answers to all registered exercises. The exercises are registered by passing the `ExerciseRegistry` instance as input argument."
    ]
   },
   {
@@ -101,7 +104,7 @@
    "id": "8",
    "metadata": {},
    "source": [
-    "A simple textarea to save students answers. Note that the save and load buttons only appear when a exercise key and registry is given"
+    "A simple text area to save students' answers. Note that the save and load buttons only appear when an exercise key and registry are given."
    ]
   },
   {
@@ -138,7 +141,7 @@
    "id": "11",
    "metadata": {},
    "source": [
-    "This is an example how to create a simple exercise."
+    "This is an example on how to create a simple exercise."
    ]
   },
   {
@@ -197,7 +200,7 @@
    "id": "14",
    "metadata": {},
    "source": [
-    "More complex widgets might need creation beforehand to allow full customization"
+    "More complex widgets might need to be created beforehand to allow full customization"
    ]
   },
   {
@@ -276,7 +279,7 @@
    "id": "17",
    "metadata": {},
    "source": [
-    "So far we always added the imports required for the code inside the code input. We need to do this because the widget is its creates its own environment (own globals) so no function from the notebook is accidently used. This however does not solve the problem when one wants to include typehints in the function signature that require imports. For that one can add the library to the globals."
+    "So far we always added the imports required for the code inside the code input. We need to do this because the widget is its creates its own environment (own globals), so no function from the notebook is accidently used. However, this does not solve the problem when one wants to include typehints in the function signature that require imports. For this, one can add the library to the globals."
    ]
   },
   {
@@ -387,7 +390,7 @@
    "id": "23",
    "metadata": {},
    "source": [
-    "The `ParametersPanel` can be also used with the same shorthand constructors as [interact](https://ipywidgets.readthedocs.io/en/latest/examples/Using%20Interact.html). Here some examples"
+    "The `ParametersPanel` can be also used with the same shorthand constructors as [interact](https://ipywidgets.readthedocs.io/en/latest/examples/Using%20Interact.html). Here are some examples."
    ]
   },
   {
@@ -413,7 +416,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "scicode",
    "language": "python",
    "name": "python3"
   },
@@ -427,7 +430,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.10"
+   "version": "3.11.11"
   }
  },
  "nbformat": 4,