diff --git a/.github/workflows/docs_check.yml b/.github/workflows/docs_check.yml
index 349b26a1f..8d75f9712 100644
--- a/.github/workflows/docs_check.yml
+++ b/.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
\ No newline at end of file
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 9d3234b26..d3dd77dcd 100644
--- a/.readthedocs.yaml
+++ b/.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:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 81e6ff57b..aec610576 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ Online Documentation
--------------------
Detailed contribution guidelines may be found in our [online documentation](
-https://opencsp.readthedocs.io/en/main/contributing.html).
+https://opencsp.readthedocs.io/en/latest/contributing.html).
Legal Disclaimer
----------------
diff --git a/contrib/scripts/sensitive_strings.py b/contrib/scripts/sensitive_strings.py
index 75e25e0b6..e28f83631 100644
--- a/contrib/scripts/sensitive_strings.py
+++ b/contrib/scripts/sensitive_strings.py
@@ -109,7 +109,7 @@ def _is_binary_file(self, file_path: str, file_name_ext: str):
ext = ext.lower()
if ext == ".ipynb":
is_binary_file = True
- if self._is_img_ext(ext):
+ elif self._is_img_ext(ext):
if ext in self._text_file_extensions:
is_binary_file = False
elif (f"{file_path}/{file_name_ext}" in self._text_file_path_name_exts) or (
@@ -118,6 +118,11 @@ def _is_binary_file(self, file_path: str, file_name_ext: str):
is_binary_file = False
else:
is_binary_file = True
+ elif ft.file_size(ft.join(file_path, file_name_ext)) > 1e6:
+ # assume any file > 1MB is a binary file, in order to prevent
+ # sensitive_strings from taking hours to check these files
+ # needlessly
+ is_binary_file = True
if not is_binary_file:
# attempt to parse the file as a text file
try:
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 1344b117f..18b5429c2 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,3 +1,4 @@
sphinx
sphinx-argparse
-sphinx-rtd-theme
\ No newline at end of file
+sphinx-rtd-theme
+nbsphinx
\ No newline at end of file
diff --git a/doc/source/conf.py b/doc/source/conf.py
index ec357e658..f1ba2d2cb 100644
--- a/doc/source/conf.py
+++ b/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.
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 79bc72528..74d7da2d6 100644
--- a/doc/source/contributing.rst
+++ b/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
diff --git a/example/csp/base_classes_and_ray_trace.ipynb b/doc/source/example/csp/base_classes_and_ray_trace.ipynb
similarity index 99%
rename from example/csp/base_classes_and_ray_trace.ipynb
rename to doc/source/example/csp/base_classes_and_ray_trace.ipynb
index cae3974cb..3b81a5de3 100644
--- a/example/csp/base_classes_and_ray_trace.ipynb
+++ b/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",
- " There are TODO notes marked in green like this.
\n",
+ " There are TODO notes marked in green like this.
\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). TODO make the link to ray trace algo work
\n",
+ "The algorithm used for ray tracing is explained in detail in TODO: ReflectedRayAlgorithm.pdf. TODO make the link to ray trace algo work
\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) TODO make the link to intersection algo work
\n",
+ "The intersection algorithm is explained in TODO:IntersectionWithPlaneAlgorithm.pdf TODO make the link to intersection algo work
\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). "
]
diff --git a/doc/source/example/csp/config.rst b/doc/source/example/csp/config.rst
index f9c641d46..d63d426f5 100644
--- a/doc/source/example/csp/config.rst
+++ b/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:
\ No newline at end of file
+ :show-inheritance:
+
+Foundation Classes and Ray Tracing
+==================================
+
+.. toctree::
+ :maxdepth: 3
+
+ base_classes_and_ray_trace
\ No newline at end of file