Documentation fix (#162)

* The installation process is updated

* Some errors that were not alowing to build the documentation were fixed

* Some fixing in the documentation generation were made.

* Some code cleanup and update of docstrings

Author: ramezquitao

doc/conf.py

@@ -46,6 +46,11 @@
     "nbsphinx",
 ]
 
+# The warnings should not be generated in the documentation, so we suppress them.
+# This may create issues later on, so be careful.
+suppress_warnings = [
+    'nbsphinx',
+]
 apidoc_module_dir = "../pyoptools"
 apidoc_output_dir = ""
 apidoc_excluded_paths = ["doc"]
@@ -227,10 +232,3 @@
 # 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

@@ -11,56 +11,43 @@ pyOpTools can be downloaded from the project GitHub repository at:
 Installing via pip
 ------------------
 
-On Windows, Mac OS and Linux you can use `pip`` to install pyOpTools.
+No matter if you're using Windows, Mac OS, or Linux, you can easily install 
+pyOpTools. Jupyter Lab is a dependency of the pyoptools package, so it will 
+also be installed automatically when you install pyoptools using `pip`. Using 
+the installed Jupyter Lab you should be able to  run all the examples in this
+documentation without any trouble.
 
-    pip install pyoptools
-
-This will install the latest available version of pyoptools.
-
-Installing it in Debian 11 (should work on any Debian derivative)
------------------------------------------------------------------
-
-pyOpTools is being developed almost exclusively using "Debian derivative" Linux
-distributions, so this installation procedure is the most tested and reliable. To
-generate the pyoptool .deb package you just need to run the following command in the project root::
+Just run this command:
 
-    make deb
+.. code-block:: bash
 
-This will create a .deb package outside the pyOpTool's source root tree. This can be installed using the command::
+    pip install pyoptools
 
-    dpkg -i python3-pyoptools_<version>_<platform>.deb
+This will install the latest version of pyoptools along with Jupyter Lab, so 
+you're all set to run the examples hassle-free.
 
-where version/platform should be adjusted accordingly.  
 
+Installing it in Debian 12 (should work on any Debian derivative)
+-----------------------------------------------------------------
 
-Installing pyOpTools inside a python virtualenv
------------------------------------------------
+The preferred method for installing pyOpTools, particularly on "Debian derivative"
+Linux distributions, is to install it as a system package. To generate the 
+pyoptools .deb package, simply navigate to the project root and execute the
+following command:
 
-After a Python3 virtualenv is created and activated, pyOpTools can be installed by running the following command, inside the project root::
-  
-    pip install -r requirements.txt
-    python3 setup.py install
-    
-.. _visualizing_pyoptools_in_jupyter:
+.. code-block:: bash
 
-Visualizing pyOpTools simulations in a JupyterLab notebook
-----------------------------------------------------------
+    make deb
 
-Before being able to visualize pyOpTools simulations in a
-`jupyterlab <https://jupyter.org>`_ Notebook, pythreejs must be enabled::
+Executing this command will generate a .deb package outside the pyOpTool's 
+source root tree. To install the generated package, use the following command:
 
-    jupyter labextension install jupyter-threejs
+.. code-block:: bash
 
-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.
+    dpkg -i python3-pyoptools_<version>_<platform>.deb
 
 
-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.
+Make sure to adjust the <version> and <platform> parameters accordingly. This 
+method eliminates the need for virtual environments and ensures a smooth 
+installation process.
 
-.. note ::
-    Please do not run jupyter lab from the pyOpTools source code directory.
-    pyOptools modules will not import correctly.

doc/modules.rst

@@ -0,0 +1,7 @@
+pyoptools
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   pyoptools

doc/notebooks/basic/00-Intro.ipynb

@@ -93,8 +93,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "L=library.Edmund.get(\"32475\")\n",
-    "SEN=CCD(size=(20,20))\n",
+    "L=library.Edmund[\"32475\"]\n",
+    "SEN=CCD(size=(20,20))#c.rotateZ(D[2])\n",
+    "    #c.rotateY(D[1])\n",
+    "    #c.rotateX(D[0])\n",
+    "\n",
     "R=parallel_beam_c(origin=(0.0, 0.0, 0.0), direction=(0.0, 0.0, 0.0), \n",
     "                  size=(10, 10), num_rays=(5, 5), wavelength=0.58929)"
    ]
@@ -181,7 +184,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
+   "version": "3.11.2"
   }
  },
  "nbformat": 4,

doc/notebooks/basic/SimpleComponents.ipynb

@@ -15,7 +15,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from pyoptools.all import *\n",
+    "from pyoptools.all import  *\n",
     "from numpy import pi,sqrt"
    ]
   },
@@ -57,7 +57,7 @@
     "\n",
     "**surflist**\n",
     "\n",
-    "> List of tuples of the form `(surface, (PosX,PosY,PosZ), (RotX,RotY,RotZ)` where `surface` is an [instance of a subclass](pyoptools.raytrace.surface.rst) of [Surface](../../pyoptools.raytrace.surface.surface.rst), `PosX,PosY,PosZ`are the surface’s vertex coordinates, and `RotX,RotY,RotZ` are the rotation angles of the surface around the X , Y , and Z axes, given in radians. The rotation about the Z axis if applied first, then the rotation about the Y axis, and finally the rotation about the X axis.\n",
+    "> List of tuples of the form `(surface, (PosX,PosY,PosZ), (RotX,RotY,RotZ)` where `surface` is an instance of a subclass of [Surface](../../pyoptools.raytrace.surface.surface.rst), `PosX,PosY,PosZ`are the surface’s vertex coordinates, and `RotX,RotY,RotZ` are the rotation angles of the surface around the X , Y , and Z axes, given in radians. The rotation about the Z axis if applied first, then the rotation about the Y axis, and finally the rotation about the X axis.\n",
     "\n",
     "**material**\n",
     "\n",
@@ -119,7 +119,7 @@
     "                      (b_face,(width/2,0,0),(0,pi/2,0)),\n",
     "                      (h_face,(0,0,0),(0,-pi/4,0)),\n",
     "                      (e1,(0,height/2,0),(pi/2,-pi/2,0)),\n",
-    "                      (e2,(0,height/2,0),(pi/2,-pi/2,0))\n",
+    "                      (e2,(0,-height/2,0),(pi/2,-pi/2,0))\n",
     "                      ],material=material.schott[\"N-BK7\"])\n",
     "Plot3D(P,size=(120,120),scale=3,rot=[(pi/6,pi/8,0)])"
    ]
@@ -167,7 +167,7 @@
     "                      (b_face,(width/2,0,0),(0,pi/2,0)),\n",
     "                      (h_face,(0,0,0),(0,-pi/4,0)),\n",
     "                      (e1,(0,height/2,0),(pi/2,-pi/2,0)),\n",
-    "                      (e2,(0,height/2,0),(pi/2,-pi/2,0))\n",
+    "                      (e2,(0,-height/2,0),(pi/2,-pi/2,0))\n",
     "                      ],material=material.schott[\"N-BK7\"])\n",
     "    return P\n",
     "P1=prism()\n",
@@ -178,6 +178,13 @@
     "Plot3D(cube,size=(120,120),scale=3,rot=[(pi/6,pi/8,0)])"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -188,7 +195,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -202,9 +209,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.6"
+   "version": "3.11.2"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 4
 }

doc/notebooks/basic/SimpleRayTraces.ipynb

@@ -511,10 +511,8 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "raw",
    "metadata": {},
-   "outputs": [],
    "source": [
     "r_b= parallel_beam_c(size=(2,2),num_rays=(5,5), wavelength=.650)\n",
     "\n",
@@ -713,7 +711,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.6"
+   "version": "3.11.2"
   }
  },
  "nbformat": 4,

doc/notebooks/basic/materials.ipynb

@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Materials"
+   ]
+  },
   {
    "cell_type": "raw",
    "metadata": {},
@@ -31,7 +38,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -45,9 +52,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.6"
+   "version": "3.11.2"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }

doc/requirements.txt

@@ -18,3 +18,5 @@ nbsphinx
 imageio
 PyYAML
 importlib_resources
+sympy
+ijson