init doc

.readthedocs.yml

@@ -11,7 +11,7 @@ build:
   apt_packages:
     - cmake
   tools:
-    python: "3.10"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CONTRIBUTING.rst

@@ -1,95 +1,4 @@
 Contributing
 ============
 
-This is an instruction of the developer tools that help you contributing.
-
-Running tests
--------------
-
-Tests can be with run using
-
-.. code-block:: bash
-
-   tox -e tests
-
-You can source the test environment of tox after a run using
-
-.. code-block:: bash
-
-    source .tox/tests/bin/activate
-
-Converting notebook test files
-##############################
-
-The we store the notebooks as converted Python file using `jupytext` for the conversion
-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
-overwritten by the conversion of `test_widget_cue_box.py` when running the test.
-
-
-Running with UI
-###############
-
-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
-
-.. code-block:: bash
-
-    pytest --driver Firefox
-
-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
-
-.. code-block:: bash
-    
-   jupyter notebook list | grep 8815
-
-or if some process is using it 
-
-.. code-block:: bash
-
-    netstat -l | grep 8815
-
-Formatting code
----------------
-
-Your code can be formatted using
-
-.. code-block:: bash
-
-   tox -e format
-
-The formatting should fix most issues with linting, but sometimes you need to manually
-fix some issues. To run the linter use
-
-.. code-block:: bash
-
-   tox -e lint
-
-
-Building documentation
-----------------------
-
-To build the docs please use
-
-.. code-block:: bash
-
-   tox -e docs
-
-To open the doc with for example firefox you can run
-
-.. code-block:: bash
-
-   firefox docs/build/html/index.html
+Please read the `developer documentation <developers.html>`_.

README.rst

@@ -1,19 +1,41 @@
-Important
-=========
-
-So far scicode-widget has been created by prototyping without much concern about the code quality. This resulted in faster development time but in cost of readability and maintanability of the code. Since we finished now the prototype phase and have converged on a set of functionalities we are satisfied with, we are in the process of refactoring the resulting code in this branch. While we are refactoring we recommend the usage of the `vertical-slice branch <https://github.com/osscar-org/scicode-widgets/tree/vertical-slice>`_ till all features have been implemented in the refactor.
-
-
 scicode-widgets
 ===============
 
 .. marker-package-description
 
-A collection of ipywidgets for the creation of interactive code demos and educational notebooks with exercises that can be checked and exported.
+*scicode-widgets* is a widget library for the purpose of creating computational
+experiments for educational content. It is targeted to teach students how to
+code and interpret computational experiments while hiding technical details and
+boiler plate code that are not essential for the learning experience. The logic
+is purely written in Python to simplify the development process for scientific
+researchers as they usually are more capable in writing Python code than
+JavaScript. It therefore builds on top of widgets provided by ipywidgets to
+creating a framework out of it.
+
+Features
+--------
+
+The core features of scicode-widgets are:
+
+**Customizable coding exercises and demos**
+
+TODO gif
+
+**Checks for students to verify their solution**
+
+TODO gif
+
+**Automatic grading using nbgrader**
+
+TODO gif
+
+Please continue with our `getting started page <getting_started.html>`_  
+for a more detailed overview of our features.
 
-Installation
-------------
+Supportde jupyter environments
+------------------------------
 
-.. code-block:: bash
+We support the following widget environments
 
-  pip install .
+* jupyterlab
+* notebook < 7

docs/requirements.txt

@@ -1 +1,3 @@
 sphinx
+nbsphinx
+sphinx-material

docs/src/api.rst

@@ -0,0 +1,29 @@
+API
+===
+
+.. automodule:: scwidgets
+   :members:
+
+exercise
+--------
+
+.. automodule:: scwidgets.exercise
+   :members:
+
+check
+-----
+
+.. automodule:: scwidgets.check
+   :members:
+
+code
+----
+
+.. automodule:: scwidgets.code
+   :members:
+
+cue
+---
+
+.. automodule:: scwidgets.cue
+   :members: