Improving python documentation

src/kete/rust/flux/common.rs

@@ -1,11 +1,11 @@
 use crate::{frame::PyFrames, vector::VectorLike};
 use itertools::Itertools;
-use nalgebra::UnitVector3;
 use kete_core::constants::{
     w1_color_correction, w2_color_correction, w3_color_correction, w4_color_correction, C_V,
 };
 use kete_core::flux::*;
 use kete_core::prelude::Error;
+use nalgebra::UnitVector3;
 use pyo3::{pyfunction, PyResult};
 
 /// Calculate the visible flux at the observer assuming a convex faceted object made up
@@ -263,6 +263,9 @@ pub fn neatm_thermal_py(
 
 /// Calculate the flux from an object using the FRM thermal model in Jansky.
 ///
+/// This is a slightly simplified FRM model, where the pole is assumed to be in the
+/// ecliptic Z direction.
+///
 /// See :doc:`../auto_examples/plot_thermal_model`
 ///
 /// Parameters

src/kete/rust/fovs/definitions.rs

@@ -15,13 +15,77 @@ use crate::{state::PyState, vector::Vector};
 pub struct PyWiseCmos(pub fov::WiseCmos);
 
 /// Field of view of a NEOS CMOS chip.
+///
+/// Parameters
+/// ----------
+/// pointing :
+///     Vector defining the center of the FOV.
+/// rotation :
+///     Rotation of the FOV in degrees.
+/// observer :
+///     State of the observer.
+/// side_id :
+///     Side ID indicating where we are in the survey.
+/// stack_id :
+///     Stack ID indicating where we are in the survey.
+/// quad_id :
+///     Quad ID indicating where we are in the survey.
+/// loop_id :
+///     Loop ID indicating where we are in the survey.
+/// subloop_id :
+///     Subloop ID indicating where we are in the survey.
+/// exposure_id :
+///     Exposure number indicating where we are in the survey.
+/// cmos_id :
+///     Which chip of the target band this represents.
+/// band :
+///     Band, can be either 1 or 2 to represent NC1/NC2.
 #[pyclass(module = "kete", frozen, name = "NeosCmos")]
 #[derive(Clone, Debug)]
 #[allow(clippy::upper_case_acronyms)]
-
 pub struct PyNeosCmos(pub fov::NeosCmos);
 
 /// Field of view of a NEOS Visit.
+///
+/// This is a collection of 4 :py:class:`NeosCmos` chips at the same moment in time.
+///         
+/// +------+-+------+-+------+-+------+   ^
+/// |  1   |g|  2   |g|  3   |g|  4   |   |
+/// |      |a|      |a|      |a|      |   y
+/// |      |p|      |p|      |p|      |   |
+/// +======+=+======+=+======+=+======+   _
+/// |- x ->
+///
+/// Where the bottom is the sun shield.
+///
+/// Parameters
+/// ----------
+/// x_width :
+///     Width of the long axis of the Visit in degrees.
+/// y_width :
+///     Width of the short axis of the Visit in degrees.
+/// gap_angle :
+///     Width of the gap between chips in degrees.
+/// pointing :
+///     Vector defining the center of the FOV.
+/// rotation :
+///     Rotation of the FOV in degrees.
+/// observer :
+///     State of the observer.
+/// side_id :
+///     Side ID indicating where we are in the survey.
+/// stack_id :
+///     Stack ID indicating where we are in the survey.
+/// quad_id :
+///     Quad ID indicating where we are in the survey.
+/// loop_id :
+///     Loop ID indicating where we are in the survey.
+/// subloop_id :
+///     Subloop ID indicating where we are in the survey.
+/// exposure_id :
+///     Exposure number indicating where we are in the survey.
+/// band :
+///     Band, can be either 1 or 2 to represent NC1/NC2.
 #[pyclass(module = "kete", frozen, name = "NeosVisit")]
 #[derive(Clone, Debug)]
 #[allow(clippy::upper_case_acronyms)]
@@ -41,16 +105,51 @@ pub struct PyZtfCcdQuad(pub fov::ZtfCcdQuad);
 pub struct PyZtfField(pub fov::ZtfField);
 
 /// Generic Rectangular Field of view.
+///
+/// There are other constructors for this, for example the
+/// :py:meth:`~RectangleFOV.from_corners` which allows construction from the 4 corners
+/// of the field.
+///
+/// Parameters
+/// ----------
+/// pointing :
+///     Vector defining the center of the field of cone.
+/// rotation :
+///     The rotation of the field of view in degrees.
+/// observer :
+///     The state of the observer.
+/// lon_width :
+///     The longitudinal width of the rectangle in degrees.
+/// lat_width:
+///     The latitudinal width of the rectangle in degrees.
 #[pyclass(module = "kete", frozen, name = "RectangleFOV")]
 #[derive(Clone, Debug)]
 pub struct PyGenericRectangle(pub fov::GenericRectangle);
 
 /// Generic Cone field of view.
+///
+/// A cone directly out from the observer's location to a point on the sky.
+///
+/// Parameters
+/// ----------
+/// pointing :
+///     Vector defining the center of the field of cone.
+/// angle :
+///     The radius of the cone in degrees, from the center to the edge of the cone.
+/// observer :
+///     The state of the observer.
 #[pyclass(module = "kete", frozen, name = "ConeFOV")]
 #[derive(Clone, Debug)]
 pub struct PyGenericCone(pub fov::GenericCone);
 
 /// Omni Directional field of view.
+///
+/// This is a good choice when the exact field is not important.
+///
+/// Parameters
+/// ----------
+/// observer :
+///     State of the omniscient observer.
 #[pyclass(module = "kete", frozen, name = "OmniDirectionalFOV")]
 #[derive(Clone, Debug)]
 pub struct PyOmniDirectional(pub fov::OmniDirectional);
@@ -227,7 +326,7 @@ impl PyWiseCmos {
         self.0.rotation.to_degrees()
     }
 
-    /// Corners of this FOV
+    /// Corners of this FOV.
     #[getter]
     pub fn corners(&self) -> Vec<Vector> {
         self.0
@@ -271,14 +370,14 @@ impl PyGenericRectangle {
     }
 
     /// Construct a new Rectangle FOV from the corners.
-    /// The corners must be provided in clockwise order.
+    /// The corners must be provided in order, either clockwise or counter-clockwise.
     ///
     /// Parameters
     /// ----------
     /// corners :
-    ///     4 Vectors which represent the corners of the FOV, these must be provided in clockwise order.
+    ///     4 Vectors which represent the corners of the FOV, these must be provided in order.
     /// observer :
-    ///     Position of the observer as a State.
+    ///     The observer as a State, this defines the time and position of the observer.
     #[staticmethod]
     pub fn from_corners(corners: [VectorLike; 4], observer: PyState) -> Self {
         let corners: [Vector3<f64>; 4] = corners.map(|x| x.into_vec(observer.frame()));
@@ -298,6 +397,7 @@ impl PyGenericRectangle {
     }
 
     /// Direction that the observer is looking.
+    /// Average center of the FOV.
     #[getter]
     pub fn pointing(&self) -> Vector {
         Vector::new(
@@ -318,7 +418,7 @@ impl PyGenericRectangle {
         self.0.lat_width().to_degrees()
     }
 
-    /// Corners of this FOV
+    /// Corners of this FOV.
     #[getter]
     pub fn corners(&self) -> Vec<Vector> {
         self.0
@@ -416,32 +516,6 @@ impl PyOmniDirectional {
 #[pymethods]
 #[allow(clippy::too_many_arguments)]
 impl PyNeosCmos {
-    /// Construct a new NEOS FOV.
-    ///
-    /// Parameters
-    /// ----------
-    /// pointing :
-    ///     Vector defining the center of the FOV.
-    /// rotation :
-    ///     Rotation of the FOV in degrees.
-    /// observer :
-    ///     State of the observer.
-    /// side_id :
-    ///     Side ID indicating where we are in the survey.
-    /// stack_id :
-    ///     Stack ID indicating where we are in the survey.
-    /// quad_id :
-    ///     Quad ID indicating where we are in the survey.
-    /// loop_id :
-    ///     Loop ID indicating where we are in the survey.
-    /// subloop_id :
-    ///     Subloop ID indicating where we are in the survey.
-    /// exposure_id :
-    ///     Exposure number indicating where we are in the survey.
-    /// cmos_id :
-    ///     Which chip of the target band this represents.
-    /// band :
-    ///     Band, can be either 1 or 2 to represent NC1/NC2.
     #[new]
     pub fn new(
         pointing: VectorLike,
@@ -583,48 +657,6 @@ impl PyNeosCmos {
 #[pymethods]
 #[allow(clippy::too_many_arguments)]
 impl PyNeosVisit {
-    /// Construct a new NEOS Visit.
-    ///
-    /// This is a collection of 4 NeosCmos fields of view, representing the
-    /// 4 chips of each band.
-    ///         
-    /// +------+-+------+-+------+-+------+   ^
-    /// |  1   |g|  2   |g|  3   |g|  4   |   |
-    /// |      |a|      |a|      |a|      |   y
-    /// |      |p|      |p|      |p|      |   |
-    /// +======+=+======+=+======+=+======+   _
-    /// |- x ->
-    ///
-    /// Where the bottom is the sun shield.
-    ///
-    /// Parameters
-    /// ----------
-    /// x_width :
-    ///     Width of the long axis of the Visit in degrees.
-    /// y_width :
-    ///     Width of the short axis of the Visit in degrees.
-    /// gap_angle :
-    ///     Width of the gap between chips in degrees.
-    /// pointing :
-    ///     Vector defining the center of the FOV.
-    /// rotation :
-    ///     Rotation of the FOV in degrees.
-    /// observer :
-    ///     State of the observer.
-    /// side_id :
-    ///     Side ID indicating where we are in the survey.
-    /// stack_id :
-    ///     Stack ID indicating where we are in the survey.
-    /// quad_id :
-    ///     Quad ID indicating where we are in the survey.
-    /// loop_id :
-    ///     Loop ID indicating where we are in the survey.
-    /// subloop_id :
-    ///     Subloop ID indicating where we are in the survey.
-    /// exposure_id :
-    ///     Exposure number indicating where we are in the survey.
-    /// band :
-    ///     Band, can be either 1 or 2 to represent NC1/NC2.
     #[new]
     pub fn new(
         x_width: f64,

src/kete/rust/state.rs

@@ -7,6 +7,21 @@ use pyo3::prelude::*;
 
 /// Representation of the state of an object at a specific moment in time.
 ///
+/// Parameters
+/// ----------
+/// desig : String
+///     Name of the object, optional.
+/// jd :
+///     The time of the state in TDB jd time, see :py:class:`kete.Time`.
+/// pos :
+///     Position of the object with respect to the center ID in au.
+/// vel :
+///     Velocity of the object with respect to the center ID in au / day.
+/// frame :
+///     The frame of reference defining the position and velocity vectors.
+/// center_id :
+///     The SPICE kernel ID which defines the central reference point, defaults to the
+///     Sun (10).
 #[pyclass(frozen, module = "kete", name = "State")]
 #[derive(Clone, Debug)]
 pub struct PyState(pub prelude::State);

src/kete/rust/time.rs

@@ -23,12 +23,15 @@ use pyo3::prelude::*;
 /// vs accuracy. Conversion between time scales is only accurate on the millisecond
 /// scale, however internal representation accuracy is on the microsecond scale.
 ///
+/// TDB is treated as equivalent to TT and TCB, because these times only differ by less
+/// than milliseconds per century.
+///
 /// Parameters
 /// ----------
 /// jd:
 ///     Julian Date in days.
 /// scaling:
-///     Accepts 'tdb', 'tai', 'utc', and 'tt', but they are converted to TDB
+///     Accepts 'tdb', 'tai', 'utc', 'tcb', and 'tt', but they are converted to TDB
 ///     immediately.
 #[pyclass(frozen, module = "kete", name = "Time")]
 #[derive(Debug)]
@@ -59,10 +62,11 @@ impl PyTime {
         Ok(match scaling.as_str() {
             "tt" => PyTime(Time::<TDB>::new(jd)),
             "tdb" => PyTime(Time::<TDB>::new(jd)),
+            "tcb" => PyTime(Time::<TDB>::new(jd)),
             "tai" => PyTime(Time::<TAI>::new(jd).tdb()),
             "utc" => PyTime(Time::<UTC>::new(jd).tdb()),
             s => Err(Error::ValueError(format!(
-                "Scaling of type ({:?}) is not supported, must be one of: 'tt', 'tdb', 'tai', 'utc'",
+                "Scaling of type ({:?}) is not supported, must be one of: 'tt', 'tdb', 'tcb', 'tai', 'utc'",
                 s
             )))?,
         })

src/kete/rust/vector.rs

@@ -10,6 +10,14 @@ use pyo3::prelude::*;
 use pyo3::{PyResult, Python};
 
 /// Vector class which is a vector along with a reference frame.
+///
+/// Parameters
+/// ----------
+/// raw : list
+///     3 floats which define the direction of the vector.
+/// frame :
+///     The frame of reference defining the coordinate frame of the vector, defaults
+///     to ecliptic.
 #[pyclass(sequence, frozen, module = "kete")]
 #[derive(Clone, Debug)]
 pub struct Vector {
@@ -283,6 +291,15 @@ impl Vector {
         self.raw[2]
     }
 
+    /// Rotate this vector around another vector by the provided angle.
+    ///
+    ///
+    /// Parameters
+    /// ----------
+    /// other : Vector
+    ///     The other vector to rotate around.
+    /// angle :
+    ///     The angle in degrees of the rotation.
     pub fn rotate_around(&self, other: VectorLike, angle: f64) -> Self {
         let self_vec = Vector3::from(self.raw);
         let other_vec = other.into_vec(self.frame());

src/kete_core/src/time/scales.rs

@@ -38,6 +38,7 @@ pub trait TimeScale {
 /// Earth).
 ///
 /// This is in agreement with TT up to about 1.7ms per century.
+/// This is in agreement with TCB up to 0.57ms per century.
 #[derive(Debug, Clone, Copy)]
 pub struct TDB;
 
@@ -51,6 +52,8 @@ impl TimeScale for TDB {
 }
 
 /// UTC Scaled JD time.
+///
+/// The international standard for communicating time.
 #[derive(Debug, Clone, Copy)]
 pub struct UTC;
 
@@ -83,10 +86,7 @@ impl TimeScale for UTC {
 /// TAI Time
 /// This is the international standard for the measurement of time.
 /// Atomic clocks around the world keep track of this time, which then gets
-/// converted to UTC time which is commonly used. UTC Time is an approximation
-/// of the current time with corrections for the rotation rate of the Earth.
-///
-/// As the Earth actually varies in its rotation speed,
+/// converted to UTC time which is commonly used.
 #[derive(Debug, Clone, Copy)]
 pub struct TAI;