Some improvement in the documentation (#144)

* Update requirements.txt

Some fixes to allow documentation build were performed

* Documentation improvement

Some documentation was added, and the requirement.txt was updated

* Update conf.py

doc/conf.py

@@ -226,3 +226,11 @@
 
 # If false, no module index is generated.
 # latex_use_modindex = True
+
+nbsphinx_prolog = """
+.. warning::
+    There is an issue with the generation of documentation from notebooks,
+    such as this page, that causes interactive plots generated using the
+    Plot3D function to appear incorrect. The examples should produce correct
+    3D plots when executed directly in Jupyter Lab.
+"""

doc/install.rst

@@ -38,27 +38,21 @@ After a Python3 virtualenv is created and activated, pyOpTools can be installed
 Visualizing pyOpTools simulations in a JupyterLab notebook
 ----------------------------------------------------------
 
-The easiest way to  use pyOpTools together with
-`jupyterlab <https://jupyter.org>`_, is to install pyOpTools
-inside a python virtualenv, and then install jupyterlab on it also::
+Before being able to visualize pyOpTools simulations in a
+`jupyterlab <https://jupyter.org>`_ Notebook, pythreejs must be enabled::
 
-    pip install jupyterlab
-
-After that the jupyter plugin pythreejs must be installed and enabled::
-
-    pip3 install pythreejs
     jupyter labextension install jupyter-threejs
 
-after this is done, you will be able to visualize the simulations using the
-:func:`~pyoptools.gui.ipywidgets.Plot3D` command.
+after this is done, you will be able to visualize the simulations using
+the :func:`~pyoptools.gui.ipywidgets.Plot3D` command. JupyterLab  and pythreejs
+are listed in the requirements.txt file so there is no need to install them
+separetelly.
+
 
 The plot window is interactive. Using the mouse, it is possible to rotate
 the image by click and drag with the left button, zoom by using the scroll
 wheel and translate by click and drag with the right button.
 
 .. note ::
-    When installing pyoptools and jupyterlab in a debian 11 machine inside a
-    virtualenv, it was necesary to install also importlib-resources::
-      
-      pip install importlib-resources
-
+    Please do not run jupyter lab from the pyOpTools source code directory.
+    pyOptools modules will not import correctly.

doc/notebooks/basic/00-Intro.ipynb

@@ -54,9 +54,7 @@
   },
   {
    "cell_type": "markdown",
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "source": [
     "## A basic introduction \n",
     "\n",
@@ -145,6 +143,7 @@
    },
    "source": [
     "## More Information\n",
+    "\n",
     "[Surfaces in pyOpTools](Surfaces.ipynb)\n",
     "[Creating components with  pyOpTools](SimpleComponents.ipynb)\n",
     "[pyOpTools predefined components](PredefinedComponents.ipynb)\n",
@@ -157,11 +156,18 @@
     "[[Simple EOD calculations](SimpleEODs.ipynb)\n",
     "-->\n"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -175,9 +181,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.10.6"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 4
 }

doc/notebooks/basic/PredefinedComponents.ipynb

@@ -31,7 +31,7 @@
     "\n",
     "Using this lens a [System](../../pyoptools.raytrace.system.system.rst#pyoptools.raytrace.system.system.System) is created. The position of the lens (the mid-point between the vertices) is the (0,0,100) coordinate. No rotation of the lens is made.\n",
     "\n",
-    "After the system is ready, a list of rays that will be propagated must be defined. In this example a list **R**, containing 5 rays is created. The origin of such [Rays](../pyoptools.raytrace.ray.ray.rst#pyoptools.raytrace.ray.ray.Ray) is defined as the coordinate (0,0,0). Each one has a different direction vector to create something similar to a point source located at the origin and aiming to the lens. The wavelength for all rays is defined as 650nm.\n",
+    "After the system is ready, a list of rays that will be propagated must be defined. In this example a list **R**, containing 5 rays is created. The origin of such [Rays](../../pyoptools.raytrace.ray.ray.rst#pyoptools.raytrace.ray.ray.Ray) is defined as the coordinate (0,0,0). Each one has a different direction vector to create something similar to a point source located at the origin and aiming to the lens. The wavelength for all rays is defined as 650nm.\n",
     "\n",
     "<div class=\"alert alert-info\">\n",
     "    \n",
@@ -41,7 +41,7 @@
     "\n",
     "After the system and the ray beam are created, the later is added to the former, and the propagation calculation is performed.\n",
     "\n",
-    "The last [Plot3d](pyoptools.gui.ipywidgets.rst#pyoptools.gui.ipywidgets.Plot3D) command creates an interactive 3D plot of the system and the propagated rays."
+    "The last [Plot3d](../../pyoptools.gui.ipywidgets.rst#pyoptools.gui.ipywidgets.Plot3D) command creates an interactive 3D plot of the system and the propagated rays."
    ]
   },
   {
@@ -304,7 +304,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -318,9 +318,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.6"
+   "version": "3.10.6"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 4
 }