Done some work on the docs

bryancole · Feb 6, 2021 · 6a29c16 · 6a29c16
1 parent 8f21193
commit 6a29c16
Show file tree

Hide file tree

Showing 11 changed files with 45 additions and 33 deletions.
diff --git a/doc/source/api_ref/index.rst b/doc/source/api_ref/index.rst
@@ -5,9 +5,9 @@ API Reference
 
 .. toctree::
 
-	ctracer
-	cmaterials
-	cfaces
-	cfields
 
-	tracer
+	faces
+	shapes
+	materials
+
+	core <core/index>
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -24,7 +24,8 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc',] # 'sphinx.ext.pngmath']
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.napoleon'] # 'sphinx.ext.pngmath']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -93,13 +94,17 @@
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 
+html_theme_options = {
+    'navigation_depth': 4,
+}
+
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
 

diff --git a/doc/source/creating_new_optics.rst b/doc/source/creating_new_optics.rst
@@ -36,12 +36,15 @@ and has .x and .y and .z members. Outside the comfort of python/numpy, vector
 algebra is significantly less pleasant. The ctracer module defines a number of
 inline functions to (partially) simplify working with vector_t's. For vector 
 arithmatic, you can use:
- - addvv_(vector_t a, vector_t b) #add two vectors
- - addvs_(vector_t a, double b) #adds a vector and a scalar
- - multvv_(vector_t a, vector_t b) #multiplies two vectors
- - multvs_(vector_t a, double b) #multiplies a vector and a scalar
+
+* addvv_(vector_t a, vector_t b) #add two vectors
+* addvs_(vector_t a, double b) #adds a vector and a scalar
+* multvv_(vector_t a, vector_t b) #multiplies two vectors
+* multvs_(vector_t a, double b) #multiplies a vector and a scalar
+
  etc. 
- Similar function are defined for subtraction and element-wise division. The
+
+Similar function are defined for subtraction and element-wise division. The
 'vv' function denote operations on two vectors, 'vs' denotes operations on a
 vector and a scalar. The trailing underscore is a convention I'm adopting to
 indicate that the method is a 'C'-method (i.e. not python callable).
@@ -133,7 +136,7 @@ materials, or share them.
 Custom Interface Materials
 --------------------------
 
-InterfaceMaterial subclasses provide a cdef method 
+InterfaceMaterial subclasses provide a cdef method:: 
 
   cdef eval_child_ray_c(self, ray_t *old_ray, 
                             unsigned int ray_idx, 

diff --git a/doc/source/examples/bessel_beam_example.rst b/doc/source/examples/bessel_beam_example.rst
@@ -1,3 +1,4 @@
+========================
 Simulating a Bessel Beam
 ========================
 

diff --git a/doc/source/examples/fresnel_diffraction_example.rst b/doc/source/examples/fresnel_diffraction_example.rst
@@ -1,3 +1,4 @@
+===================================
 Fresnel Diffraction From A BeamStop
 ===================================
 

diff --git a/doc/source/examples/index.rst b/doc/source/examples/index.rst
@@ -6,4 +6,5 @@ Examples
 .. toctree::
 
 	bessel_beam_example
-	fresnel_diffraction_example
+	fresnel_diffraction_example
+	michelson_interferometer_example
diff --git a/doc/source/general_optics.rst b/doc/source/general_optics.rst
@@ -4,9 +4,9 @@ The General Optic Framework
 The General Optic framework provides the most flexible means of defining optical components. The GeneralLens class
 is an optic which is composed of:
 
-* A shape (from raypier.shapes)
-* A list of surfaces (from raypier.faces)
-* A list of materials (from raypier.materials)
+* A shape (from :py:mod:`raypier.shapes`)
+* A list of surfaces (from :py:mod:`raypier.faces`)
+* A list of materials (from :py:mod:`raypier.materials`)
 
 These are high-level objects which aim to streamline the process of configuring a custom optical element. The general optic
 framework is appropriate for optical elements which fit the "planar" model of a outline defined in the XY-plane with a 
@@ -22,9 +22,9 @@ coordinate system. The optic can have any position and orientation in the global
 
 There are two shape primitives, at the time of writing:
 
- * RectangleShape
+ * :py:class:`RectangleShape`
 
- * CircleShape
+ * :py:class:`CircleShape`
 
 There are two more I have yet to implement, being PolygonShape and EllipseShape.
 
@@ -47,7 +47,7 @@ Surfaces
 The surfaces represent the geometry of the faces of the GeneralLens. While a simple singlet lens 
 will have two surfaces, a doublet will have 3. In fact, any number of surfaces can be added.
 
-I wanted to call the _surfaces_ list of the GeneralLens "faces" but faces is already overused as an 
+I wanted to call the *surfaces* list of the GeneralLens "faces" but faces is already over-used as an 
 attribute name.
 
 There are 6 core face types supported by the General Optic framework:
@@ -58,11 +58,16 @@ There are 6 core face types supported by the General Optic framework:
 * Conic (a conic surface of revolution)
 * Aspheric
 * Axicon
+* Distortion
 
 These all have a "mirror" boolean trait. If this is true, the face is considered 100% reflective.
 Otherwise, the reflection and transmission characteristics will be derived from the dielectric 
 material coefficients on either side of the surface.
 
+The DistortionFace object is a special type of Face that wraps another "base face" with some sort 
+of geometric distortion function (for example, a Zernike polynomial function). The range of available
+distortion functions can be found in the :py:mod:`raypier.distortions` module.
+
 Materials
 .........
 

diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -9,12 +9,14 @@ Welcome to Raypier's documentation!
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    introduction
+   exploring_the_gui
+   ray_collections
+   ray_sources
    general_optics
    gaussian_beamlet_propagation
-   cython_branch_info
    creating_new_optics
 
    Examples <examples/index>

diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst
@@ -69,13 +69,4 @@ While all of the above objects are optional, you probably want at least one sour
 will be rather uninteresting). 
 
 
-Exploring the GUI
-=================
-
-Raypier is based on the Traits/TraitsUI framework. The Traits library provides a notification framework and improved type-declaration.
-TraitsUI is a GUI framework that extends Traits to make developing custom GUIs fast and easy. The UI for *any* traited object
-can be invoked with a call to my_object.configure_traits(). Typically, I recommend you define your base optical model in a 
-script where an instance of RayTraceModel is created, then launch ui GUI with a call to the model's configure_traits() method. Lets see 
-this in action::
-
 
diff --git a/examples/michelson_interferometer_example.py b/examples/michelson_interferometer_example.py
@@ -27,12 +27,14 @@
 f1 = PlanarFace(mirror=True)
 f2 = SphericalFace(curvature=2000.0, mirror=True)
 
-m1 = GeneralLens(shape=shape,
+m1 = GeneralLens(name="Mirror 1",
+                 shape=shape,
                  surfaces=[f1],
                  centre=(0,20,0),
                  direction=(0,-1,0))
 
-m2 = GeneralLens(shape=shape,
+m2 = GeneralLens(name="Mirror 2",
+                 shape=shape,
                  surfaces=[f2],
                  centre=(20,0,0),
                  direction=(-1,0,0))

diff --git a/raypier/bases.py b/raypier/bases.py
@@ -384,6 +384,7 @@ def update_complete(self):
                           show_border=True,
                           label="Direction"
                           ),
+                   label="Geometry"
                     )