Jupyter notebooks and doc check

.github/workflows/docs_check.yml

@@ -31,5 +31,6 @@ jobs:
           pip install -r requirements.txt
           cd doc
           pip install -r requirements.txt
+          sudo apt install -y pandoc
           ./make_docs.sh
 

.readthedocs.yaml

@@ -10,10 +10,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
-    # You can also specify other tool versions:
-    # nodejs: "19"
-    # rust: "1.64"
-    # golang: "1.19"
+  # Install pandoc for including jupyter notebooks in our generated docs
+  apt_packages:
+    - pandoc
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

doc/requirements.txt

@@ -1,3 +1,4 @@
 sphinx
 sphinx-argparse
-sphinx-rtd-theme
+sphinx-rtd-theme
+nbsphinx

doc/source/conf.py

@@ -45,6 +45,7 @@
     "sphinx.ext.todo",
     "sphinxarg.ext",
     "sphinx_rtd_theme",
+    "nbsphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

doc/source/contributing.rst

@@ -24,6 +24,25 @@ NumPy-style docstrings with bulleted lists. We require NumPy compliant docstring
 Models, Public Classes, and Public Functions. For more internal and development-facing 
 documentation please use hash tags.
 
+All documentation is verified to pass sphinx-build without errors via https://github.com/sandialabs/OpenCSP/blob/develop/.github/workflows/docs_check.yml.
+Solely documentation that has a associated sphinx config in https://github.com/sandialabs/OpenCSP/tree/develop/doc/source will be included in this online documentation.
+There are several different ways to include documentation in the sphinx config depending on what the source of documentation is. For general guidance, please see
+https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html. For examples of how this is currently done in OpenCSP, please see any of the config.rst files in doc/source. A common 
+use-case is to include NewClass with its documented and undocumented non-private members, to do that you would add the following to 
+https://github.com/sandialabs/OpenCSP/blob/develop/doc/source/library_reference/app/sofast/config.rst:
+
+    .. code-block:: rst
+
+        opencsp.app.sofast.lib.NewClass
+        ===============================
+
+        .. currentmodule:: opencsp.app.sofast.lib.NewClass
+
+        .. automodule:: opencsp.app.sofast.lib.NewClass
+           :members:
+           :undoc-members:
+           :show-inheritance:
+
 We highly recommend using Visual Studio Code for development. If using VS Code,
 please install the following plugins:
 
@@ -72,7 +91,7 @@ commits:
    for FILE in $(git diff --cached --name-only | egrep '.*\.py$')
    do
      if [ -e $FILE ]; then
-       black $FILE -C -S
+       black $FILE --line-length 120 -C -S
        git add $FILE
      fi
    done

example/csp/base_classes_and_ray_trace.ipynb → doc/source/example/csp/base_classes_and_ray_trace.ipynb

@@ -8,13 +8,6 @@
     "===================================="
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "*Last updated May 21, 2024*"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -27,7 +20,7 @@
     "- solar fields (to be renamed heliostat fields)\n",
     "\n",
     "It will also talk about using ray tracing with these objects.\n",
-    "<p style=\"color:green\"> There are TODO notes marked in green like this. </p>\n",
+    "<h3 style=\"color:green\"> There are TODO notes marked in green like this. </h3>\n",
     "\n",
     "If you are following along and altering the code to better understand what is going on that is great. There are some blocks that can only really run one time, and if you accidentally run that block when you should not have then just reload the doc. At worst it generally only takes about 2-3 minutes to run all the cells."
    ]
@@ -922,7 +915,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The algorithm used for ray tracing is explained in detail in [ReflectedRayAlgorithm.pdf](../../doc/common/lib/csp/ReflectedRayAlgorithm.pdf). <h3 style=\"color:green\"> TODO make the link to ray trace algo work</h3>\n",
+    "The algorithm used for ray tracing is explained in detail in TODO: ReflectedRayAlgorithm.pdf. <h3 style=\"color:green\"> TODO make the link to ray trace algo work</h3>\n",
     "\n",
     "OpenCSP ray tracing requires many points, the normal vectors at those points (to know how light sohuld reflect) and a light source. Any `RayTraceable` object will have a `survey_of_points` function. This function will give a list of points and normal vectors at those points for a given `Resolution`."
    ]
@@ -1294,7 +1287,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The intersection algorithm is explained in [IntersectionWithPlaneAlgorithm.pdf](../../doc/common/lib/csp/IntersectionWithPlaneAlgorithm.pdf) <h3 style=\"color:green\"> TODO make the link to intersection algo work</h3>\n",
+    "The intersection algorithm is explained in TODO:IntersectionWithPlaneAlgorithm.pdf <h3 style=\"color:green\"> TODO make the link to intersection algo work</h3>\n",
     "\n",
     "We want to know where the individual light rays intersect with some plane. We can use the ray traces from earlier: `trace` and `trace2` from the [`RayTrace` section](#raytrace-class). These are small ray traces, but we might want to analyse exactly where the rays intersect. Lets say we want to know how the reflections intersect with the $xy$ plane at $z=1$. We will have the first one be blue(where the point light source was at the focal point)  and the second one be red (where the light source was about at the $2f$ point). "
    ]

doc/source/example/csp/config.rst

@@ -5,4 +5,12 @@ Optics and Ray tracing
 
 .. automodule:: example.csp.example_optics_and_ray_tracing
    :members:
-   :show-inheritance:
+   :show-inheritance:
+
+Foundation Classes and Ray Tracing
+==================================
+
+.. toctree::
+   :maxdepth: 3
+
+   base_classes_and_ray_trace