Jupyter Documentation replaced by RST (#676)

* Jupyter Documentation replaced by RST

As per [issue 597](#597), unit_testing.ipynb, adding_to_the_api_documentation.ipynb and creating_an_example_notebook.ipynb files are replaced with the corresponding RST files. The thumbnails in the gallery is ensured.

* Jupyter Documentation replaced by RST, black conf.py

* %load statements are replaced with literalinclude

During conversion from Jupyter to RST format, %load statements are replaced with literalinclude so that the imported code / docstring is up to date with the source file.

* Update docs/source/development/adding_to_the_api_documentation.rst

* Update docs/source/development/adding_to_the_api_documentation.rst

* Update docs/source/development/adding_to_the_api_documentation.rst

Co-authored-by: Jonathan Wenger <[email protected]>

docs/source/conf.py

@@ -137,6 +137,13 @@
     "--InlineBackend.rc={'figure.dpi': 150}",
 ]
 
+# Thumbnails for .rst notebooks
+nbsphinx_thumbnails = {
+    "development/creating_an_example_notebook": "_images/jupyter.png",
+    "development/adding_to_the_api_documentation": "_images/sphinx_logo.png",
+    "development/unit_testing": "_images/test-results.png",
+}
+
 # -- Intersphinx configuration ----------------------------------------------
 
 # Whenever Sphinx encounters a cross-reference that has no matching target in the

docs/source/development/adding_to_the_api_documentation.rst

@@ -0,0 +1,142 @@
+Adding to the API Documentation
+===============================
+
+Documentation is an integral part of every collaborative software
+project. Good documentation not only encourages users of the package to
+try out different functionalities, but it also makes maintaining and
+expanding code significantly easier. Every code contribution to the
+package must come with appropriate documentation of the API. This guide
+details how to do this.
+
+Docstrings
+----------
+
+The main form of documentation are docstrings, multi-line comments
+beneath a class or function definition with a specific syntax, which
+detail its functionality. This package uses the `NumPy docstring
+format <https://numpydoc.readthedocs.io/en/latest/format.html#numpydoc-docstring-guide%3E>`__.
+As a rule, all functions which are exposed to the user *must* have
+appropriate docstrings. Below is an example of a docstring for a
+probabilistic numerical method 
+named ``problinsolve`` defined in ``_problinsolve.py`` in the ``linalg`` subpackage.
+
+.. literalinclude:: ../../../src/probnum/linalg/_problinsolve.py
+   :lines: 1-163
+
+**General Rules**
+
+-  Cover ``Parameters``, ``Returns``, ``Raises`` and ``Examples``, if
+   applicable, in every publicly visible docstring—in that order.
+-  Examples are tested via doctest. Ensure ``doctest`` does not fail by
+   running the test suite.
+-  Include appropriate ``References``, in particular for probabilistic
+   numerical methods.
+-  Do not use docstrings as a clutch for spaghetti code!
+
+**Parameters**
+
+-  Parameter types are automatically documented via type hints in the
+   function signature.
+-  Always provide shape hints for objects with a ``.shape`` attribute in
+   the following form:
+
+.. code:: python
+
+   """
+   Parameters
+   ----------
+   arr
+       *(shape=(m, ) or (m, n))* -- Parameter array of an example function.
+   """
+
+-  Hyperparameters should have default values and explanations on how to
+   choose them.
+-  For callables provide the expected signature as part of the
+   docstring: ``foobar(x, y, z, \*\*kwargs)``. Backslashes remove
+   semantic meaning from special characters.
+
+**Style**
+
+-  Stick to the imperative style of writing in the docstring header
+   (i.e.: first line).
+
+   -  Yes: “Compute the value”.
+   -  No: “This function computes the value / Let’s compute the value”.
+
+   The rest of the explanation talks about the function, e. g. “This
+   function computes the value by computing another value”.
+-  Use full sentences inside docstrings when describing something.
+
+   -  Yes: “This value is irrelevant, because it is not being passed on”
+   -  No: “Value irrelevant, not passed on”.
+
+-  When in doubt, more explanation rather than less. A little text
+   inside an example can be helpful, too.
+-  A little maths can go a long way, but too much usually adds
+   confusion.
+
+Interface Documentation
+-----------------------
+
+Which functions and classes actually show up in the documentation is
+determined by an ``__all__`` statement in the corresponding
+``__init__.py`` file inside a module. The order of this list is also
+reflected in the documentation. For example, ``linalg`` has the
+following ``__init__.py``:
+
+.. literalinclude:: ../../../src/probnum/linalg/__init__.py
+
+
+If you are documenting a subclass, which has a different path in the
+file structure than the import path due to ``__all__`` statements, you
+can correct the links to superclasses in the documentation via the
+``.__module__`` attribute.
+
+Sphinx
+------
+
+ProbNum uses `Sphinx <https://www.sphinx-doc.org/en/master/>`__ to parse
+docstrings in the codebase automatically and to create its API
+documentation. You can configure Sphinx itself or its extensions in the
+``./docs/conf.py`` file.
+
+.. code:: ipython3
+
+    from IPython.display import Image
+    
+    display(Image(filename="../assets/img/developer_guides/sphinx_logo.png", embed=True))
+
+
+
+.. image:: ../assets/img/developer_guides/sphinx_logo.png
+
+
+ProbNum makes use of a number of Sphinx plugins to improve the API
+documentation, for example to parse Jupyter notebooks. The full list
+of used packages can be found in ``./docs/sphinx-requirements.txt`` and
+``./docs/notebook-requirements.txt``.
+
+Building and Viewing the Documentation
+--------------------------------------
+
+In order to build the documentation locally and view the HTML version of
+the API documentation, simply run:
+
+.. code:: bash
+
+   tox -e docs
+
+This creates a static web page under ``./docs/_build/html/`` which you
+can view in your browser by opening ``./docs/_build/html/intro.html``.
+
+Alternatively, if you want to build the docs in your current environment
+you can manually execute
+
+.. code:: bash
+
+   cd docs
+   make clean
+   make html
+
+For more information on ``tox``, check out the `general development
+instructions <../development/pull_request.md>`__.

docs/source/development/creating_an_example_notebook.rst

@@ -0,0 +1,139 @@
+Creating an Example Notebook
+============================
+
+Functionality of ProbNum is explained in detail in the form of Jupyter
+notebooks in the `tutorials
+section <../development/developer_guides.rst>`__ of the documentation.
+If you want to add an example showcasing the functionality of ProbNum,
+follow the instructions below.
+
+.. code:: ipython3
+
+    from IPython.display import Image
+    
+    display(Image(url='https://upload.wikimedia.org/wikipedia/commons/thumb/3/38/Jupyter_logo.svg/1200px-Jupyter_logo.svg.png', 
+                  width=250, embed=True))
+
+
+
+.. image:: ../assets/img/developer_guides/jupyter.png
+   :width: 250px
+
+
+Setting up the Jupyter Notebook
+-------------------------------
+
+We begin by creating a new Jupyter notebook under
+``./docs/source/tutorials/``. If you want some guidance on the style,
+you can copy one of the existing notebooks.
+
+Style and HTML conversion
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you create your own ensure that the first cell is a markdown cell
+containing an upper level markdown header (# Header) to be converted
+correctly to HTML. This header will appear in the sidebar of the
+documentation. In the body of the notebook only use headers of a lower
+level (## and more) to ensure correct sidebar appearance.
+
+In order to keep the style of the output consistent, the first code cell
+of the notebook should contain the following code snippet.
+
+.. code:: ipython3
+
+    # Make inline plots vector graphics instead of raster graphics
+    %matplotlib inline
+    from IPython.display import set_matplotlib_formats
+    
+    set_matplotlib_formats("pdf", "svg")
+    
+    # Plotting
+    import matplotlib.pyplot as plt
+    
+    plt.style.use("../probnum.mplstyle")
+
+This snippet defines the style of plots generated by Matplotlib. For
+example, it defines the font and makes sure any output is a vector
+graphic. If you need to use specific LaTeX packages, e.g. to label your
+plots, simply add them to the list via:
+
+.. code:: ipython3
+
+    plt.rcParams["text.latex.preamble"] += r" \usepackage{siunitx}"
+
+.. code:: ipython3
+
+    plt.rcParams["text.latex.preamble"]
+
+
+
+
+.. parsed-literal::
+
+    '\\usepackage[cm]{sfmath} \\usepackage{amsmath, amssymb} \\usepackage{bm} \\renewcommand{\\familydefault}{\\sfdefault} \\usepackage{siunitx}'
+
+
+
+Adding the Notebook to the Website
+----------------------------------
+
+Now that you’ve created your notebook, we have to add it in the right
+place on the website. Check the existing topics in
+``./docs/source/tutorials/<some_topic>.rst`` and add your notebook name
+to the appropriate ``nbgallery``.
+
+.. code:: rst
+
+   .. nbgallery::
+
+      my_example_notebook
+
+This creates a gallery item on the corresponding topic page in the
+documentation under tutorials. You can set the preview image for your
+example notebook by choosing a cell that produces an output plot and
+adding a tag to the metadata of the corresponding Jupyter notebook cell.
+
+.. code:: json
+
+   {
+       "tags": [
+           "nbsphinx-thumbnail"
+       ]
+   }
+
+Viewing the Result
+------------------
+
+In order to view the resulting page from the notebook, build the
+documentation locally via
+
+.. code:: bash
+
+   tox -e docs
+
+If the notebook compiles successfully, you should see similar output to
+the one below.
+
+.. code:: bash
+
+   ...
+   copying static files... ... done
+   copying extra files... done
+   dumping search index in English (code: en)... done
+   dumping object inventory... done
+   build succeeded.
+
+   The HTML pages are in _build/html.
+
+   Build finished. The HTML pages are in _build/html.
+   ___________________________________ summary ____________________________________
+     docs: commands succeeded
+     congratulations :)
+
+You can now view your results locally by opening the website in
+``./docs/_build/html``. Make sure you fix any error messages popping up
+in the build before making a pull request to the ``main`` branch. Once
+you’ve created a pull request
+`ReadTheDocs <https://readthedocs.org/projects/probnum/>`__ will
+automatically build the documentation including your new example
+notebook.