Skip to content

Cleanup RTD and docstrings in src #125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 30, 2025
Merged

Cleanup RTD and docstrings in src #125

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b5feb9b
initial rewriting of docs
tulga-rdn Mar 6, 2025
330afe7
Update src/scwidgets/check/_check.py
agoscinski Jun 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 23 additions & 20 deletions docs/src/check.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
]
},
{
Expand All @@ -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."
]
},
{
Expand All @@ -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."
]
},
{
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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."
]
},
{
Expand All @@ -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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -250,7 +253,7 @@
"tags": []
},
"source": [
"## Obfuscating the reference solution with fingerprint"
"## Obfuscating the reference solution with a fingerprint"
]
},
{
Expand All @@ -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",
Expand Down Expand Up @@ -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. "
]
},
{
Expand All @@ -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"
]
},
{
Expand Down
28 changes: 14 additions & 14 deletions docs/src/developers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down Expand Up @@ -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

Expand Down
23 changes: 13 additions & 10 deletions docs/src/exercises.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand Down Expand Up @@ -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"
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand Down Expand Up @@ -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."
]
},
{
Expand All @@ -413,7 +416,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3 (ipykernel)",
"display_name": "scicode",
"language": "python",
"name": "python3"
},
Expand All @@ -427,7 +430,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.10"
"version": "3.11.11"
}
},
"nbformat": 4,
Expand Down
Loading
Loading