docs: notebooks: How to create notebooks

Signed-off-by: mHash1m <hashimchaudry23@gmail.com>

docs/contributing/index.rst

@@ -18,6 +18,7 @@ or post in the `Gitter Chat <https://gitter.im/dffml/community>`_.
     git
     testing
     docs
+    notebooks
     consoletest
     debugging
     editors/index

docs/contributing/notebooks.rst

@@ -0,0 +1,49 @@
+Notebooks
+=========
+
+Code Formatting
+---------------
+
+After having written a notebook, it should be made sure that the code is
+in the right format, ie. the ``black`` formatters code style. A
+convenient way to achieve this in ``jupyter notebook`` is to install the
+`jupyter-black extension <https://github.com/drillan/jupyter-black>`_.
+
+Testing
+-------
+
+Once you've made an example notebook, the code inside the notebook will need
+to be tested before it can be merged into the codebase. Notebooks cannot be
+tested in the typical manner, as a notebook file consists of more than just the code.
+To test notebooks, DFFML utilizes 
+`testbook <https://testbook.readthedocs.io/en/latest/usage/index.html>`_.
+
+``testbook`` provides different ways to access, unittest and mock the code inside
+a notebook. Following is an example of how `testbook` can be used to test a notebook,
+in this case,
+:doc:`../examples/notebooks/moving_between_models`
+
+.. literalinclude:: /../tests/notebooks/test_moving_between_models.py
+
+Documentation
+-------------
+
+Notebooks are added to the documentation by utilizing ``nbsphinx`` and
+``nbsphinx-link``. ``nbsphinx`` only lets you add notebooks that are
+present in the same directory to the documentation. To overcome this,
+``nbsphinx-link`` is used, which allows you to create a symblic link to
+notebooks in other directories.
+
+You can create the link to a notebook in a file with extention ``.nblink`` as follows
+
+.. literalinclude:: /examples/notebooks/moving_between_models.nblink
+
+After the link has been created, the ``nblink`` file is simply added to a toctree
+to be displayed in the documentation
+
+.. code-block:: text
+
+    .. toctree::
+        :maxdepth: 2
+
+        moving_between_models

tests/notebooks/test_moving_between_models.py

@@ -3,9 +3,14 @@
 
 
 class TestNotebook(unittest.TestCase):
+    # Giving testbook the path to notebook
     @testbook("examples/notebooks/moving_between_models.ipynb")
     def test_stdout(tb, self):
+        # Execute specific cells using a range
         tb.execute_cell(range(0, 6))
+        # Using inject function to insert and execute our own code during the execution of the notebook.
+        # Here, we use it to mock the cached_download() call to change the directory of saving the dataset
+        # to be able to gitignore it later on and avoid spam.
         tb.inject(
             """
             data_path = await cached_download(
@@ -15,10 +20,13 @@ def test_stdout(tb, self):
             )
             """
         )
+        # Insert and execute an assertion.
         tb.inject(
             "assert 'tests/notebooks/data/wine_quality.csv' in str(data_path)"
         )
+        # Execute the rest of the cells.
         tb.execute_cell(range(8, 21))
+        # Get the output of specific cells and make assertions.
         assert tb.cell_output_text(13) == "1599 1279 320"
         assert "Accuracy1" and "Accuracy2" in tb.cell_output_text(19)
         assert "confidence" and "value" in tb.cell_output_text(21)