Merge pull request #191 from e10harvey/doc_strings_exist_common_csp

common/lib/csp: Test docs
sandialabs · Jan 7, 2025 · b2addd5 · b2addd5
2 parents 504d299 + a3d6891
commit b2addd5
Show file tree

Hide file tree

Showing 22 changed files with 1,484 additions and 221 deletions.
diff --git a/doc/gen_library_ref_rst_from_class_list.sh b/doc/gen_library_ref_rst_from_class_list.sh
@@ -0,0 +1,38 @@
+#!/bin/bash
+echo "Usage example: "
+echo "    ./gen_library_ref_rst_from_class_list.sh \\"
+echo "    ./source/library_reference/common/lib/csp \\"
+echo "    CSP \\"
+echo "    \"This is a collection of CSP utilities for OpenCSP." "opencsp.common.lib.csp.Facet, opencsp.common.lib.csp.FacetEnsemble, opencsp.common.lib.csp.HeliostatAbstract, opencsp.common.lib.csp.HeliostatAzEl, opencsp.common.lib.csp.HeliostatConfiguration, opencsp.common.lib.csp.LightPath, opencsp.common.lib.csp.LightPathEnsemble, opencsp.common.lib.csp.LightSource, opencsp.common.lib.csp.LightSourcePoint, opencsp.common.lib.csp.LightSourceSun, opencsp.common.lib.csp.MirrorAbstract, opencsp.common.lib.csp.MirrorParametric, opencsp.common.lib.csp.MirrorParametricRectangular, opencsp.common.lib.csp.MirrorPoint, opencsp.common.lib.csp.OpticOrientationAbstract, opencsp.common.lib.csp.RayTrace, opencsp.common.lib.csp.RayTraceable, opencsp.common.lib.csp.Scene, opencsp.common.lib.csp.SolarField, opencsp.common.lib.csp.StandardPlotOutput, opencsp.common.lib.csp.Tower, opencsp.common.lib.csp.VisualizeOrthorectifiedSlopeAbstract, opencsp.common.lib.csp.sun_position, opencsp.common.lib.csp.sun_track, opencsp.common.lib.csp.visualize_orthorectified_image\"\\"
+
+DOC_PATH="${1:?Error: DOC_PATH is unset}"
+DOC_SHORT_DESCRIPTOR="${2:?Error: DOC_SHORT_DESCRIPTOR is unset}"
+DOC_LONG_DESCRIPTOR="${3:?Error: DOC_LONG_DESCRIPTOR is unset}"
+CLASS_LIST="${4:?Error: CLASS_LIST is unset}"
+
+sed_cmd=sed
+which gsed &> /dev/null
+ret=$?
+if [ $ret -eq 0 ]; then
+  sed_cmd=gsed
+fi
+
+mkdir -p $DOC_PATH || true
+rm -i $DOC_PATH/config.rst
+rm -i $DOC_PATH/index.rst
+
+for class in $(echo $CLASS_LIST); do
+  sans_comma=$(echo $class | tr -d ',')
+  cat template_config | ${sed_cmd} "s/__MODULE__/$sans_comma/g" >> $DOC_PATH/config.rst
+done
+
+echo "$DOC_SHORT_DESCRIPTOR" >> $DOC_PATH/index.rst
+footer_len=$(echo $DOC_SHORT_DESCRIPTOR | wc -c)
+python -c "print('=' * ${footer_len})" >> $DOC_PATH/index.rst
+echo "" >> $DOC_PATH/index.rst
+
+echo "$DOC_LONG_DESCRIPTOR" >> $DOC_PATH/index.rst
+echo "" >> $DOC_PATH/index.rst
+cat template_index >> $DOC_PATH/index.rst
+
+echo -n "$DOC_PATH" | awk -F 'library_reference/' '{print "   "$2"/index.rst"}' >> ./source/library_reference/index.rst
diff --git a/doc/source/library_reference/common/lib/csp/config.rst b/doc/source/library_reference/common/lib/csp/config.rst
@@ -0,0 +1,257 @@
+Facet
+=====
+
+.. currentmodule:: opencsp.common.lib.csp.Facet
+
+.. automodule:: opencsp.common.lib.csp.Facet
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.FacetEnsemble
+
+.. automodule:: opencsp.common.lib.csp.FacetEnsemble
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+Heliostat
+=========
+
+.. currentmodule:: opencsp.common.lib.csp.HeliostatAbstract
+
+.. automodule:: opencsp.common.lib.csp.HeliostatAbstract
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.HeliostatAzEl
+
+.. automodule:: opencsp.common.lib.csp.HeliostatAzEl
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.HeliostatConfiguration
+
+.. automodule:: opencsp.common.lib.csp.HeliostatConfiguration
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+LightPath
+=========
+
+.. currentmodule:: opencsp.common.lib.csp.LightPath
+
+.. automodule:: opencsp.common.lib.csp.LightPath
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.LightPathEnsemble
+
+.. automodule:: opencsp.common.lib.csp.LightPathEnsemble
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+LightSource
+===========
+
+.. currentmodule:: opencsp.common.lib.csp.LightSource
+
+.. automodule:: opencsp.common.lib.csp.LightSource
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.LightSourcePoint
+
+.. automodule:: opencsp.common.lib.csp.LightSourcePoint
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.LightSourceSun
+
+.. automodule:: opencsp.common.lib.csp.LightSourceSun
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+Mirror
+======
+
+.. currentmodule:: opencsp.common.lib.csp.MirrorAbstract
+
+.. automodule:: opencsp.common.lib.csp.MirrorAbstract
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.MirrorParametric
+
+.. automodule:: opencsp.common.lib.csp.MirrorParametric
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.MirrorParametricRectangular
+
+.. automodule:: opencsp.common.lib.csp.MirrorParametricRectangular
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.MirrorPoint
+
+.. automodule:: opencsp.common.lib.csp.MirrorPoint
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+RayTrace and OpticOrientation
+=============================
+
+.. currentmodule:: opencsp.common.lib.csp.OpticOrientationAbstract
+
+.. automodule:: opencsp.common.lib.csp.OpticOrientationAbstract
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.RayTrace
+
+.. automodule:: opencsp.common.lib.csp.RayTrace
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.RayTraceable
+
+.. automodule:: opencsp.common.lib.csp.RayTraceable
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+Scene
+=====
+
+.. currentmodule:: opencsp.common.lib.csp.Scene
+
+.. automodule:: opencsp.common.lib.csp.Scene
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+SolarField
+==========
+
+.. currentmodule:: opencsp.common.lib.csp.SolarField
+
+.. automodule:: opencsp.common.lib.csp.SolarField
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+Tower
+=====
+
+.. currentmodule:: opencsp.common.lib.csp.Tower
+
+.. automodule:: opencsp.common.lib.csp.Tower
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+Sun
+===
+
+.. currentmodule:: opencsp.common.lib.csp.sun_position
+
+.. automodule:: opencsp.common.lib.csp.sun_position
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.sun_track
+
+.. automodule:: opencsp.common.lib.csp.sun_track
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+Plotting
+========
+
+.. currentmodule:: opencsp.common.lib.csp.StandardPlotOutput
+
+.. automodule:: opencsp.common.lib.csp.StandardPlotOutput
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.VisualizeOrthorectifiedSlopeAbstract
+
+.. automodule:: opencsp.common.lib.csp.VisualizeOrthorectifiedSlopeAbstract
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
+.. currentmodule:: opencsp.common.lib.csp.visualize_orthorectified_image
+
+.. automodule:: opencsp.common.lib.csp.visualize_orthorectified_image
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
diff --git a/doc/source/library_reference/common/lib/csp/index.rst b/doc/source/library_reference/common/lib/csp/index.rst
@@ -0,0 +1,9 @@
+CSP
+====
+
+This is a collection of CSP utilities for OpenCSP.
+
+.. toctree::
+   :maxdepth: 1
+
+   config.rst
diff --git a/doc/source/library_reference/index.rst b/doc/source/library_reference/index.rst
@@ -11,4 +11,5 @@ This section describes the OpenCSP classes and interfaces.
    app/camera_calibration/index.rst
    app/scene_reconstruction/index.rst
    common/lib/cv/index.rst
-   common/lib/camera/index.rst
+   common/lib/camera/index.rst
+   common/lib/csp/index.rst
diff --git a/doc/template_config b/doc/template_config
@@ -0,0 +1,9 @@
+.. currentmodule:: __MODULE__
+
+.. automodule:: __MODULE__
+   :members:
+   :special-members: __init__
+   :undoc-members:
+   :show-inheritance:
+   :member-order: groupwise
+
diff --git a/doc/template_index b/doc/template_index
@@ -0,0 +1,4 @@
+.. toctree::
+   :maxdepth: 1
+
+   config.rst
diff --git a/opencsp/common/lib/csp/HeliostatAbstract.py b/opencsp/common/lib/csp/HeliostatAbstract.py
@@ -42,11 +42,12 @@
 class HeliostatAbstract(RayTraceable, OpticOrientationAbstract, ABC):
     """
     Heliostat representation.
-    Parameters:
-        -----------
-        facet_ensemble: FacetEnsemble
-            List of facets, in order from top-left to bottom-right (row major order).
-            The facet names should be their position in the list (1-indexed).
+
+    Parameters
+    ----------
+    facet_ensemble: FacetEnsemble
+        List of facets, in order from top-left to bottom-right (row major order).
+        The facet names should be their position in the list (1-indexed).
     """
 
     def __init__(
@@ -129,18 +130,18 @@ def movement_transform(self, config: HeliostatConfiguration) -> TransformXYZ:
 
         Example
         -------
-        ```python
-        # override movement_transform in HeliostatAbstract
-        def movement_transform(self, az_angle: float, el_angle: float):
-            '''possible movement_transform for an oversimplified
-            azimuth and elevation based heliostat.'''
-            az_rotation = Rotation.from_euler('z', az_angle)
-            transform_az = TransformXYZ.from_R(az_rotation)
-            el_rotation = # rotate about the proper vector
-            transform_el = TransformXYZ.from_R(el_rotation)
-            composite_transform = transform_el * transform_az
-            return composite_transform
-        ```
+        .. code-block:: python
+
+            # override movement_transform in HeliostatAbstract
+            def movement_transform(self, az_angle: float, el_angle: float):
+                '''possible movement_transform for an oversimplified
+                azimuth and elevation based heliostat.'''
+                az_rotation = Rotation.from_euler('z', az_angle)
+                transform_az = TransformXYZ.from_R(az_rotation)
+                el_rotation = # rotate about the proper vector
+                transform_el = TransformXYZ.from_R(el_rotation)
+                composite_transform = transform_el * transform_az
+                return composite_transform
         """
         ...