doc fixes

doc/conf.py

@@ -23,6 +23,9 @@
 
 # The full version, including alpha/beta/rc tags
 import dsgp4
+import sys
+import os
+sys.path.insert(0, os.path.abspath('../dsgp4'))
 
 release = dsgp4.__version__
 
@@ -32,7 +35,11 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_nb", "sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.autosummary"]
+extensions = ["myst_nb", "sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.intersphinx", "sphinx.ext.autosummary","sphinx.ext.napoleon"]
+
+autosummary_generate = True
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
 
 intersphinx_mapping = {
     "numpy": ("https://numpy.org/doc/stable/", None),

dsgp4/newton_method.py

@@ -34,8 +34,8 @@ def initial_guess(tle_0, time_mjd, target_state=None):
     Args:
         - tle_0 (``dsgp4.tle.TLE``): starting TLE at time0
         - new_date (``datetime.datetime``): new date of the TLE, as a datetime object
-        - target_state (``torch.tensor``): a 2x3 tensor for the position and velocity of the state. If None, then this is computed
-                                           by propagating `tle_0` at the `new_date`.
+        - target_state (``torch.tensor``): a 2x3 tensor for the position and velocity of the state. If None, then this is computed 
+                                            by propagating `tle_0` at the `new_date`.
 
     Returns:
         - y0 (``torch.tensor``): initial guess for the TLE elements. In particular, y0 contains
@@ -152,21 +152,20 @@ def update_TLE(old_tle,y0):
 
 def newton_method(tle_0, time_mjd, target_state=None, new_tol=1e-12,max_iter=50):
     """
-    This method performs Newton method starting from an initial TLE and a given propagation time. The objective
+    This method performs Newton method starting from an initial TLE and a given propagation time. The objective 
     is to find a TLE that accurately reconstructs the propagated state, at observation time.
 
     Args:
         - tle_0 (``dsgp4.tle.TLE``): starting TLE (i.e., TLE at a given initial time)
-        - new_date (``datetime.datetime``): time (as a datetime object) at which we want the state to be propagated, and we want the TLE at that time
-        - target_state (``torch.tensor``): 2x3 tensor representing target state. If None, then this is directly computed by propagating the TLE at `new_date`
-        - new_tol (``float``): newton tolerance
-        - max_iter (``int``): maximum iterations for Newton's method
+        - time_mjd (``float``): time at which we want to propagate the TLE (in Modified Julian Date)
+        - target_state (``torch.tensor``): a 2x3 tensor for the position and velocity of the state. If None, then this is computed by propagating `tle_0` at the `new_date`.
+        - new_tol (``float``): tolerance for the Newton method
+        - max_iter (``int``): maximum number of iterations for the Newton method
 
     Returns:
-        - tle (``dsgp4.tle.TLE``): found TLE
-        - y (``torch.tensor``): returns the solution that satisfied F(y)=0 (with a given tolerance)
-                                or (in case no convergence is reached within the tolerance) the best
-                                guess found in `max_iter` iterations
+        - next_tle (``dsgp4.tle.TLE``): TLE corresponding to the propagated state
+        - y0 (``torch.tensor``): initial guess for the TLE elements. In particular, y0 contains the following elements (see SGP4 for a thorough description of these parameters):
+
     """
     i=0
     tol=1e9

dsgp4/plot.py

@@ -11,7 +11,7 @@ def plot_orbit(states, r_earth=6378.137, elevation_azimuth=None, ax=None, *args,
                                      position (in km) and the second the spacecraft velocity (in km/s). Reference frame is TEME.
         - r_earth (``float``): Earth radius in km (used for the plot). Default value is 6378.137 km.
         - elevation_azimuth (``tuple``): tuple of two floats, representing the elevation and azimuth angles of the plot. If None, the default values are used.
-        - ax (``matplotlib.axes._subplots.Axes3DSubplot``): 3D axis object
+        - ax (``matplotlib.axes._subplots.Axes3DSubplot``): 3D axis object. If None, a new figure is created.
         - *args, **kwargs: additional arguments to be passed to the plot function
     
     Returns:
@@ -53,20 +53,30 @@ def plot_orbit(states, r_earth=6378.137, elevation_azimuth=None, ax=None, *args,
     plt.tight_layout()
     return ax
 
-def plot_tles(tles, file_name=None, figsize = (36,18), show=True, axs=None, return_axs=False, log_yscale=False, *args, **kwargs):
+def plot_tles(tles, 
+              file_name=None, 
+              figsize = (36,18), 
+              show=True, 
+              axs=None, 
+              return_axs=False, 
+              log_yscale=False, 
+              *args, 
+              **kwargs):
     """
     This function takes a list of tles as input and plots the histograms of some of their elements.
-
-    Inputs
-    ----------
-    - tles (`list`): list of tles, where each element is a `dsgp4.tle.TLE` object.
-    - save_fig (`bool`): boolean variable, if True, figure is saved to a file.
-    - file_name (`str`): name of the file (including path) where the plot is to be saved.
-    - figsize (`tuple`): figure size.
-
-    Outputs
-    ----------
-    - ax (`numpy.ndarray`): array of AxesSubplot objects
+    
+    Args:    
+        - tles (``list``): list of tles, where each element is a ``dsgp4.tle.TLE`` object.
+        - file_name (``str``): name of the file (including path) where the plot is to be saved.
+        - figsize (``tuple``): figure size.
+        - show (``bool``): if True, the plot is shown.
+        - axs (``numpy.ndarray``): array of AxesSubplot objects.
+        - return_axs (``bool``): if True, the function returns the array of AxesSubplot objects.
+        - log_yscale (``bool``): if True, the y-scale is logarithmic.
+        - *args, **kwargs: additional arguments to be passed to the hist function.
+    
+    Returns:    
+        - ax (``numpy.ndarray``): array of AxesSubplot objects
     """
     #I collect all the six variables from the TLEs:
     mean_motion, eccentricity, inclination, argument_of_perigee, raan, b_star, mean_anomaly, mean_motion_first_derivative, mean_motion_second_derivative = [], [], [], [], [], [], [], [], []

dsgp4/tle.py

@@ -28,10 +28,10 @@ def read_satellite_catalog_number(string):
     the corresponding satellite catalog number.
 
     Args:
-        string (`str`): string line
+        string (``str``): string line
     
     Returns:
-        `int`: satellite catalog number
+        ``int``: satellite catalog number
     """
     if not string[0].isalpha():
         return int(string)
@@ -47,11 +47,11 @@ def load_from_lines(lines, opsmode='i'):
     """
     This function takes a TLE as a list of strings and returns both itself and its dictionary representation.
     Args:
-        lines (`list`): TLE data in the form of a list
-        opsmode (`str`): operation mode, either 'i' or 'a'
+        lines (``list``): TLE data in the form of a list
+        opsmode (``str``): operation mode, either 'i' or 'a'
     Returns:
-        `list`: TLE data in the form of a list
-        `dict`: TLE data in the form of a dictionary
+        ``list``: TLE data in the form of a list
+        ``dict``: TLE data in the form of a dictionary
     """
     if isinstance(lines, str):
         lines = util.get_non_empty_lines(lines)