Fixes to documentation (#42)

* fix docs api parameter rendering

* fixing docs

* expose SpkInfo

* fix doc typos

* mypy

docs/conf.py

@@ -41,17 +41,17 @@
 
 
 # Napoleon settings
-napoleon_google_docstring = True
+napoleon_google_docstring = False
 napoleon_numpy_docstring = True
-napoleon_include_init_with_doc = True
+napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = False
 napoleon_use_admonition_for_examples = False
 napoleon_use_admonition_for_notes = False
 napoleon_use_admonition_for_references = False
 napoleon_use_ivar = False
-napoleon_use_param = False
-napoleon_use_rtype = False
+napoleon_use_param = True
+napoleon_use_rtype = True
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

src/neospy/conversion.py

@@ -168,7 +168,7 @@ def compute_tisserand(
     inclination:
         Inclination of the small body with respect to the perturbing body, in units of
         Degrees.
-    preturbing_semi_major:
+    perturbing_semi_major:
         Semi major axis of the parent body, in units of AU.
     """
     cos_incl = np.cos(np.radians(inclination))
@@ -303,8 +303,8 @@ def mag_to_flux(mag: float, zero_point=3631) -> float:
 
     Parameters
     ----------
-    flux:
-        Flux in Jy.
+    mag:
+        AB Magnitude.
     zero_point:
         Flux in Jy where the magnitude is zero.
     """

src/neospy/irsa.py

@@ -105,6 +105,9 @@ def query_irsa_tap(
         The URL of the TAPS service to query, this defaults to IRSA.
     auth :
         An optional (username, password), this may be used to access restricted data.
+    timeout :
+        Timeout for web queries. This will raise an exception if the servers to not
+        respond within this time.
     verbose :
         Print status responses as they are fetched from IRSA.
     """
@@ -171,6 +174,24 @@ def plot_fits_image(fit, vmin=-3, vmax=7, cmap="bone_r"):
     """
     Plot a FITS image, returning a WCS object which may be used to plot future points
     correctly onto the current image.
+
+    This estimates the standard deviation, subtracts the median, and scales the
+    displayed image by number of standard deviations from the median value.
+
+    This returns the WCS which is constructed during the plotting process.
+
+    This will use the existing matplotlib plotting axis if available.
+
+    Parameters
+    ----------
+    fit:
+        Fits file from Astropy.
+    vmin :
+        Minimum number of standard deviations below the median to plot.
+    vmax :
+        Maximum number of standard deviations above the median to plot.
+    cmap :
+        Color map to use for the plot.
     """
     data = np.nan_to_num(fit.data)
     wcs = WCS(fit.header, relax=True)
@@ -195,6 +216,27 @@ def annotate_plot(
     """
     Add an annotation for a point in a FITS plot, this requires a world coordinate
     system (wcs) as returned by the plotting function above.
+
+    Parameters
+    ----------
+    wcs :
+        An Astropy World Coordinate system from the image.
+    ra :
+        The RA in degrees.
+    dec :
+        The DEC in degrees.
+    text :
+        Optional text to display.
+    px_gap :
+        How many pixels should the annotation be offset from the specified RA/DEC.
+    length :
+        Length of the bars in pixels.
+    lw :
+        Line width of the bars.
+    c :
+        Color of the bars, uses matplotlib colors.
+    text_color :
+        If text is provided, this defines the text color.
     """
     x, y = wcs.world_to_pixel(SkyCoord(ra, dec, unit="deg"))
     total = length + px_gap

src/neospy/mpc.py

@@ -32,6 +32,10 @@ def find_obs_code(name: str):
     >>> neospy.mpc.find_obs_code("Palomar Mountain")
     (33.35412, 243.13746, 1.69615, 'Palomar Mountain', '675')
 
+    Parameters
+    ----------
+    name :
+        Name of the observatory, this can be a partial name, or obs code.
     """
     codes = _core.observatory_codes()
     found = []
@@ -184,7 +188,7 @@ def pack_permanent_designation(unpacked):
     return pack_comet_designation(unpacked)
 
 
-def unpack_provisional_designation(packed):
+def unpack_provisional_designation(packed: str):
     """
     Accepts a packed MPC provisional designation and returns an unpacked provisional
     designation.
@@ -196,7 +200,7 @@ def unpack_provisional_designation(packed):
 
     Parameters
     ----------
-    packed : str
+    packed :
         A packed 7 character provisional MPC designation of an object.
     """
     if len(packed) == 12:
@@ -211,15 +215,15 @@ def unpack_provisional_designation(packed):
     if int(year) < 1925:
         year = "A" + year[1:]
     loop = _mpc_hex.index(packed[4]) * 10 + int(packed[5])
-    loop = "" if loop == 0 else str(loop)
+    loop_str = "" if loop == 0 else str(loop)
     order = packed[6]
     if order.isnumeric() or order.islower():
         # it's a comet
         return unpack_comet_designation(packed)
-    return year + " " + packed[3] + order + loop
+    return year + " " + packed[3] + order + loop_str
 
 
-def pack_provisional_designation(unpacked):
+def pack_provisional_designation(unpacked: str):
     """
     Accepts an unpacked MPC provisional designation and returns a packed provisional
     designation.
@@ -231,7 +235,7 @@ def pack_provisional_designation(unpacked):
 
     Parameters
     ----------
-    unpacked : str
+    unpacked :
         An unpacked provisional MPC designation of an object.
     """
     year, designation = unpacked.split()
@@ -253,7 +257,7 @@ def pack_provisional_designation(unpacked):
     return century + decade + half_month + loop + subloop + order
 
 
-def pack_satellite_designation(unpacked):
+def pack_satellite_designation(unpacked: str):
     """
     Accepts an unpacked MPC planetary satellite designation and returns a packed
     designation.
@@ -265,7 +269,7 @@ def pack_satellite_designation(unpacked):
 
     Parameters
     ----------
-    unpacked : str
+    unpacked :
         An unpacked satellite MPC designation of an object.
     """
     planet, satnum = unpacked.split()
@@ -279,7 +283,7 @@ def pack_satellite_designation(unpacked):
     return f"{pout:1s}{digout:03d}S"
 
 
-def unpack_satellite_designation(packed):
+def unpack_satellite_designation(packed: str):
     """
     Accepts a packed MPC satellite designation and returns an unpacked
     designation.
@@ -291,7 +295,7 @@ def unpack_satellite_designation(packed):
 
     Parameters
     ----------
-    packed : str
+    packed :
         A packed 5 character satellite MPC designation of an object.
     """
 
@@ -313,7 +317,7 @@ def unpack_satellite_designation(packed):
     return planets[packed[0]] + " " + int_to_roman(int(packed[1:4]))
 
 
-def pack_comet_designation(unpacked):
+def pack_comet_designation(unpacked: str):
     """
     Accepts an unpacked MPC provisional designation and returns a packed provisional
     designation.
@@ -328,7 +332,7 @@ def pack_comet_designation(unpacked):
 
     Parameters
     ----------
-    unpacked : str
+    unpacked :
         An unpacked MPC comet designation of an object.
     """
 
@@ -383,7 +387,7 @@ def pack_comet_designation(unpacked):
                 return comet_type + pack_provisional_designation(unpacked)
 
 
-def unpack_comet_designation(packed):
+def unpack_comet_designation(packed: str):
     """
     Accepts a packed MPC comet designation and returns an unpacked provisional
     designation.
@@ -395,7 +399,7 @@ def unpack_comet_designation(packed):
 
     Parameters
     ----------
-    packed : str
+    packed :
         A packed 5,7, or 8 character provisional MPC designation of an object.
     """
     if len(packed) == 5:
@@ -418,7 +422,7 @@ def unpack_comet_designation(packed):
         return comet_add + unpack_provisional_designation(packed)
 
 
-def unpack_designation(packed):
+def unpack_designation(packed: str):
     """
     Accepts either a packed provisional designation or permanent designation and returns
     the unpacked representation.
@@ -431,7 +435,7 @@ def unpack_designation(packed):
 
     Parameters
     ----------
-    packed : str
+    packed :
         A packed 5, 7, or 8 character MPC designation of an object.
     """
     packed = packed.strip()
@@ -445,7 +449,7 @@ def unpack_designation(packed):
     raise SyntaxError(f"This designation could not be unpacked '{packed}'")
 
 
-def pack_designation(unpacked):
+def pack_designation(unpacked: str):
     """
     Accepts either a unpacked provisional designation or permanent designation and
     returns the packed representation.
@@ -458,7 +462,7 @@ def pack_designation(unpacked):
 
     Parameters
     ----------
-    unpacked : str
+    unpacked :
         An unpacked designation to be packed into either a permanent or provisional
         designation.
     """
@@ -776,7 +780,7 @@ def table_to_states(orbit_dataframe):
     return states
 
 
-def int_to_roman(num):
+def int_to_roman(num: int):
     """Convert an integer to a Roman numeral."""
     if not isinstance(num, int):
         raise TypeError("Input needs to be an integer")
@@ -793,7 +797,7 @@ def int_to_roman(num):
     return "".join(result)
 
 
-def roman_to_int(num):
+def roman_to_int(num: str):
     """Convert a Roman numeral to an integer."""
 
     if not isinstance(num, str):

src/neospy/propagation.py

@@ -11,6 +11,7 @@
 
 from .spice import SpiceKernels
 from .vector import Vector, State
+from .fov import FOVList
 from . import _core  # pylint: disable=no-name-in-module
 
 logger = logging.getLogger(__name__)
@@ -75,7 +76,7 @@ def propagate_two_body(
 
     Parameters
     ----------
-    vec_state:
+    states:
         The input vector state to propagate.
     jd:
         The desired time at which to estimate the objects' state.
@@ -128,8 +129,8 @@ def moid(state: State, other: Optional[State] = None):
 
     Parameters
     ----------
-    states:
-        The state describing a number of objects.
+    state:
+        The state describing an object.
     other:
         The state of the object to calculate the MOID for, if this is not provided, then
         Earth is fetched from :class:`~neospy.spice.SpiceKernels` and is used in
@@ -140,18 +141,20 @@ def moid(state: State, other: Optional[State] = None):
     return _moid_single(state, other)
 
 
-def state_visible(states: list[State], fovs, dt: float = 3) -> list[list[State]]:
+def state_visible(
+    states: list[State], fovs: FOVList, dt: float = 3
+) -> list[list[State]]:
     """
-    Given a state and field of view, return only the objects which are visible to the
+    Given states and field of view, return only the objects which are visible to the
     observer, adding a correction for optical light delay.
 
     Objects are propagated using 2 body physics to the time of the FOV if time steps are
     less than the specified `dt`.
 
     parameters
     ----------
-    state:
-        A state which does not already have a specified FOV.
+    states:
+        States which do not already have a specified FOV.
     fov:
         A field of view from which to subselect objects which are visible.
     dt:

src/neospy/rust/flux/models.rs

@@ -15,12 +15,18 @@ use crate::{frame::PyFrames, vector::VectorLike};
 ///
 /// Parameters
 /// ----------
-/// fluxes : Total fluxes per band in units of Jy / Steradian.
-/// thermal_fluxes : Black body specific fluxes per band in units of Jy / Steradian.
-/// hg_fluxes : Reflected light specific fluxes per band in units of Jy / Steradian.
-/// v_band_magnitude : Expected magnitude in the V-band using the HG model.
-/// v_band_flux : Expected flux in the V-band using the HG model.
-/// magnitudes : Magnitudes in the different bands if zero mags were available.
+/// fluxes :
+///     Total fluxes per band in units of Jy / Steradian.
+/// thermal_fluxes :
+///     Black body specific fluxes per band in units of Jy / Steradian.
+/// hg_fluxes :
+///     Reflected light specific fluxes per band in units of Jy / Steradian.
+/// v_band_magnitude :
+///     Expected magnitude in the V-band using the HG model.
+/// v_band_flux :
+///     Expected flux in the V-band using the HG model.
+/// magnitudes :
+///     Magnitudes in the different bands if zero mags were available.
 #[pyclass(frozen, module = "neospy.flux", name = "ModelResults")]
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct PyModelResults(pub neospy_core::flux::ModelResults);

src/neospy/rust/state.rs

@@ -57,7 +57,7 @@ impl PyState {
     ///
     /// Parameters
     /// ----------
-    /// frame : Frame
+    /// frame : Frames
     ///     New frame to change to.
     pub fn change_frame(&self, frame: PyFrames) -> PyResult<Self> {
         let mut state = self.0.clone();