Merge pull request #4 from igoumiri/docs/small-fixes

Add basic documentation + small fixes

.gitignore

@@ -49,6 +49,8 @@ cover/
 
 # Sphinx documentation
 docs/_build/
+docs/source/api
+docs/source/modules
 
 # Jupyter Notebook
 **/*.ipynb_checkpoints

docs/README.rst

@@ -0,0 +1,22 @@
+SSAPy Documentation
+===================
+
+Building the docs
+-----------------
+
+First, build and _install_ `ssapy` following the `Installing SSAPy <https://LLNL.github.io/SSAPy/installation.html>`_ section of the documentation.
+
+Then, to build the HTML documentation locally, from the `docs` directory, run
+
+.. code-block:: bash
+
+    make html
+
+(run it twice to generate all files.)
+
+Then open `_build/html/index.html` to browse the docs locally.
+
+Alternatively, you can run `sphinx-autobuild . _build/html` to start a server that watches for changes in `/docs`
+and regenerates the HTML docs automatically while serving them at http://127.0.0.1:8000/.
+
+Note that if you updated docstrings, you'll need to re-build and re-install ssapy before re-building the docs.

docs/source/installation.rst

@@ -34,7 +34,7 @@ These requirements can be easily installed on most modern macOS and Linux system
        .. code-block:: console
 
           brew update
-          brew install gcc git git-lfs python3 svn graphviz
+          brew install gcc git git-lfs python3 graphviz
 
 Installation
 ------------

ssapy/accel.py

@@ -1,3 +1,7 @@
+"""
+Classes for modeling accelerations.
+"""
+
 import numpy as np
 
 from . import _ssapy
@@ -101,6 +105,7 @@ def __eq__(self, rhs):
 
 
 class AccelProd(Accel):
+    """Acceleration defined as the product of an acceleration with a constant factor."""
     def __init__(self, accel, factor):
         super().__init__()
         self.accel = accel

ssapy/body.py

@@ -1,3 +1,7 @@
+"""
+Classes representing celestial bodies.
+"""
+
 import erfa
 import numpy as np
 from .utils import _gpsToTT, iers_interp

ssapy/constants.py

@@ -1,3 +1,7 @@
+"""
+A collection of physical constants.
+"""
+
 import numpy as np
 
 # GM

ssapy/correlate_tracks.py

@@ -2012,7 +2012,7 @@ def summarize_tracklet(arc):
     pmra, pmdec: the proper motion in right ascension and declination
     dpmra, dpmdec: the uncertainty in the proper motion in RA and declination
     """
-    unit = ssapy.utils.lb2unit(arc['ra'].to(u.rad).value,
+    unit = ssapy.utils.lb_to_unit(arc['ra'].to(u.rad).value,
                                arc['dec'].to(u.rad).value)
     meanunit = np.mean(unit, axis=0)
     # defines tangent plane
@@ -2033,7 +2033,7 @@ def summarize_tracklet(arc):
     rasig = np.sqrt(np.diag(racovar))
     decp, deccovar = np.polyfit(dt, dectp, 1, w=1./dpos, cov='unscaled')
     decsig = np.sqrt(np.diag(deccovar))
-    meanra, meandec = ssapy.utils.unit2lb(meanunit[None, :])
+    meanra, meandec = ssapy.utils.unit_to_lb(meanunit[None, :])
     rap[1] += meanra[0]
     decp[1] += meandec[0]
     out = [(rap[1]*u.rad, decp[1]*u.rad),

ssapy/ellipsoid.py

@@ -1,3 +1,11 @@
+"""
+Class to handle transformations between ECEF x,y,z coords and geodetic
+longitude, latitude, and height.
+
+Technically, only handles a one-axis ellipsoid, defined via a flattening
+parameter f, but that's good enough for simple Earth models.
+"""
+
 import numpy as np
 
 from ._ssapy import Ellipsoid

ssapy/gravity.py

@@ -1,8 +1,12 @@
+"""
+Classes for gravity-related accelerations.
+"""
+
 # from functools import lru_cache
 
 import numpy as np
 
-from .accel import Accel, _invnorm
+from .accel import Accel as _Accel, _invnorm
 from .utils import find_file, norm
 from . import _ssapy
 
@@ -220,7 +224,7 @@ def __eq__(self, rhs):
         )
 
 
-class AccelThirdBody(Accel):
+class AccelThirdBody(_Accel):
     """Acceleration due to a third body.
 
     Parameters
@@ -254,7 +258,7 @@ def __call__(self, r, v, t, **kwargs):
         return -self.body.mu * (s / norm(s)**3 - d / norm(d)**3)
 
 
-class AccelHarmonic(Accel):
+class AccelHarmonic(_Accel):
     """Acceleration due to a harmonic potential.
 
     Parameters

ssapy/io.py

@@ -1,3 +1,7 @@
+"""
+Collection of functions to read from and write to various file formats.
+"""
+
 import datetime
 import numpy as np
 from astropy.time import Time