Merge pull request DOI-USGS#131 from chkim-usgs/sphinx_docs

Add docs structure

README.md

@@ -8,13 +8,13 @@ A library to leverage python wrapped Community Sensor Models (CSMs) for common s
 
 ## References:
 
-- CSM (usgscsm): https://github.com/USGS-Astrogeology/usgscsm
-- Abstraction Layer for Ephemerides (ALE): https://github.com/USGS-Astrogeology/ale
+- CSM (usgscsm): https://github.com/DOI-USGS/usgscsm
+- Abstraction Layer for Ephemerides (ALE): https://github.com/DOI-USGS/ale
 <hr>
 
 ## Overview
 
-We currently use Knoten to help test our supported CSM implementations against well established [ISIS3 camera models](https://github.com/USGS-Astrogeology/ISIS3). In short, The CSM standard, now at version 3.0.3, is a framework that provides a well-defined application program interface (API) for multiple types of sensors and has been widely adopted by remote sensing software systems (e.g. BAE's Socet GXP, Harris Corp.'s ENVI, Hexagon's ERDAS Imagine, and recently added to the NASA AMES Stereo Pipeline [ASP]). Our support for CSM is explained in this [abstract](https://www.hou.usra.edu/meetings/informatics2018/pdf/6040.pdf) and a recently submitted paper (not yet available). Currently, we support **Framing** and **Pushbroom** (line scanner) types of sensor models in the [usgscsm](https://github.com/USGS-Astrogeology/usgscsm) library. 
+We currently use Knoten to help test our supported CSM implementations against well established [ISIS3 camera models](https://github.com/DOI-USGS/ISIS3). In short, The CSM standard, now at version 3.0.3, is a framework that provides a well-defined application program interface (API) for multiple types of sensors and has been widely adopted by remote sensing software systems (e.g. BAE's Socet GXP, Harris Corp.'s ENVI, Hexagon's ERDAS Imagine, and recently added to the NASA AMES Stereo Pipeline [ASP]). Our support for CSM is explained in this [abstract](https://www.hou.usra.edu/meetings/informatics2018/pdf/6040.pdf) and a recently submitted paper (not yet available). Currently, we support **Framing** and **Pushbroom** (line scanner) types of sensor models in the [usgscsm](https://github.com/DOI-USGS/usgscsm) library. 
 
 A secondary requirement for our CSM implementation requires an ALE-generated Image Support Data (ISD). ISDs contain the [SPICE-derived](https://naif.jpl.nasa.gov/naif/toolkit.html) positional (and when needed velocity) description for each image. You can find several generated JSON-formatted examples [here](examples/data/)
 

docs/_static/css/custom.css

@@ -0,0 +1,7 @@
+@import 'material_sphinx.css';
+
+.sig.sig-object.py{
+    font-feature-settings: "kern";
+    font-family: "Roboto Mono", "Courier New", Courier, monospace;
+    background: #f8f8f8;
+}

docs/conf.py

@@ -10,9 +10,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
@@ -27,8 +27,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -38,6 +37,8 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+autosummary_generate = False
+autoclass_content = "class"
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -46,6 +47,9 @@
 #
 html_theme = 'sphinx_material'
 
+html_static_path = ['_static']
+html_css_files = ['css/custom.css']
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -81,9 +85,9 @@
     'repo_name': 'Project',
 
     # Visible levels of the global TOC; -1 means unlimited
-    'globaltoc_depth': 3,
+    'globaltoc_depth': 2,
     # If False, expand all TOC entries
-    'globaltoc_collapse': False,
+    'globaltoc_collapse': True,
     # If True, show hidden TOC entries
     'globaltoc_includehidden': False,
-}
+}

docs/index.rst

@@ -4,16 +4,27 @@ Knoten
 A library to leverage python wrapped Community Sensor Models (CSMs) for common spatial/sensor operations and testing.
 
 
+Table of Contents
+-----------------
+
+:Date: |today|
+
+.. toctree::
+   :maxdepth: 2
+
+   library/index
+
+
 References
 ----------
 
-- CSM (usgscsm): https://github.com/USGS-Astrogeology/usgscsm
-- Abstraction Layer for Ephemerides (ALE): https://github.com/USGS-Astrogeology/ale
+- CSM (usgscsm): https://github.com/DOI-USGS/usgscsm
+- Abstraction Layer for Ephemerides (ALE): https://github.com/DOI-USGS/ale
 
 Overview
 --------
 
-We currently use Knoten to help test our supported CSM implementations against well established `ISIS3 camera models <https://github.com/USGS-Astrogeology/ISIS3>`_. In short, The CSM standard, now at version 3.0.3, is a framework that provides a well-defined application program interface (API) for multiple types of sensors and has been widely adopted by remote sensing software systems (e.g. BAE's Socet GXP, Harris Corp.'s ENVI, Hexagon's ERDAS Imagine, and recently added to the NASA AMES Stereo Pipeline [ASP]). Our support for CSM is explained in this `abstract <https://www.hou.usra.edu/meetings/informatics2018/pdf/6040.pdf>`_ and a recently submitted paper (not yet available). Currently, we support **Framing** and **Pushbroom** (line scanner) types of sensor models in the `usgscsm <https://github.com/USGS-Astrogeology/usgscsm>`_ library. 
+We currently use Knoten to help test our supported CSM implementations against well established `ISIS3 camera models <https://github.com/DOI-USGS/ISIS3>`_. In short, The CSM standard, now at version 3.0.3, is a framework that provides a well-defined application program interface (API) for multiple types of sensors and has been widely adopted by remote sensing software systems (e.g. BAE's Socet GXP, Harris Corp.'s ENVI, Hexagon's ERDAS Imagine, and recently added to the NASA AMES Stereo Pipeline [ASP]). Our support for CSM is explained in this `abstract <https://www.hou.usra.edu/meetings/informatics2018/pdf/6040.pdf>`_ and a recently submitted paper (not yet available). Currently, we support **Framing** and **Pushbroom** (line scanner) types of sensor models in the `usgscsm <https://github.com/DOI-USGS/usgscsm>`_ library. 
 
 A secondary requirement for our CSM implementation requires an ALE-generated Image Support Data (ISD). ISDs contain the `SPICE-derived <https://naif.jpl.nasa.gov/naif/toolkit.html>`_ positional (and when needed velocity) description for each image. You can find several generated JSON-formatted examples `here <https://github.com/DOI-USGS/knoten/blob/main/examples/data>`_.
 

docs/library/bundle.rst

@@ -0,0 +1,9 @@
+:mod:`bundle` --- Bundle Adjustment
+======================================
+
+The :mod:`knoten.bundle` module
+
+.. automodule:: knoten.bundle
+  :synopsis:
+  :members:
+  :show-inheritance:

docs/library/csm.rst

@@ -0,0 +1,9 @@
+:mod:`csm` --- CSM Tools
+=========================
+
+The :mod:`knoten.csm` module
+
+.. automodule:: knoten.csm
+  :synopsis:
+  :members:
+  :show-inheritance:

docs/library/index.rst

@@ -0,0 +1,18 @@
+.. _index:
+
+#################
+Library Reference
+#################
+
+:Date: |today|
+
+-----------------------------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   bundle
+   csm
+   surface
+   utils
+   vis

docs/library/surface.rst

@@ -0,0 +1,9 @@
+:mod:`surface` --- Target Surface
+======================================
+
+The :mod:`knoten.surface` module
+
+.. automodule:: knoten.surface
+  :synopsis:
+  :members:
+  :show-inheritance:

docs/library/utils.rst

@@ -0,0 +1,9 @@
+:mod:`utils` --- Utilities
+======================================
+
+The :mod:`knoten.utils` module
+
+.. automodule:: knoten.utils
+  :synopsis:
+  :members:
+  :show-inheritance:

docs/library/vis.rst

@@ -0,0 +1,9 @@
+:mod:`vis` --- Visualization
+======================================
+
+The :mod:`knoten.vis` module
+
+.. automodule:: knoten.vis
+  :synopsis:
+  :members:
+  :show-inheritance:

knoten/csm.py

@@ -271,8 +271,9 @@ def _compute_intersection_distance(intersection, next_intersection):
             abs(intersection.z - next_intersection.z))
 
 def generate_boundary(isize, npoints=10):
-    '''
+    """
     Generates a bounding box given a camera model
+
     Parameters
     ----------
     isize : list
@@ -284,7 +285,7 @@ def generate_boundary(isize, npoints=10):
     -------
     boundary : list
                List of full bounding box
-    '''
+    """
     x = np.linspace(0, isize[0], npoints)
     y = np.linspace(0, isize[1], npoints)
     boundary = [(i,0.) for i in x] + [(isize[0], i) for i in y[1:]] +\
@@ -293,7 +294,7 @@ def generate_boundary(isize, npoints=10):
     return boundary
 
 def generate_latlon_boundary(camera, boundary, dem=0.0, radii=None, **kwargs):
-    '''
+    """
     Generates a latlon bounding box given a camera model
 
     Parameters
@@ -318,7 +319,7 @@ def generate_latlon_boundary(camera, boundary, dem=0.0, radii=None, **kwargs):
            List of latitude values
     alts : list
            List of altitude values
-    '''
+    """
 
     if radii is None:
         semi_major, semi_minor = get_radii(camera)
@@ -344,9 +345,10 @@ def generate_latlon_boundary(camera, boundary, dem=0.0, radii=None, **kwargs):
     return lons, lats, alts
 
 def generate_gcps(camera, boundary, radii=None):
-    '''
+    """
     Generates an area of ground control points formated as:
     <GCP Id="" Info="" Pixel="" Line="" X="" Y="" Z="" /> per record
+
     Parameters
     ----------
     camera : object
@@ -361,7 +363,7 @@ def generate_gcps(camera, boundary, radii=None):
     -------
     gcps : list
            List of all gcp records generated
-    '''
+    """
     if radii is None:
         semi_major, semi_minor = get_radii(camera)
     else:
@@ -381,8 +383,9 @@ def generate_gcps(camera, boundary, radii=None):
     return gcps
 
 def generate_latlon_footprint(camera, boundary, dem=0.0, radii=None, **kwargs):
-    '''
+    """
     Generates a latlon footprint from a csmapi generated camera model
+
     Parameters
     ----------
     camera : object
@@ -401,7 +404,7 @@ def generate_latlon_footprint(camera, boundary, dem=0.0, radii=None, **kwargs):
     -------
     : object
       ogr multipolygon containing between one and two polygons
-    '''
+    """
     if radii is None:
         semi_major, semi_minor = get_radii(camera)
     else:
@@ -463,8 +466,9 @@ def generate_latlon_footprint(camera, boundary, dem=0.0, radii=None, **kwargs):
     return multipoly
 
 def generate_bodyfixed_footprint(camera, boundary, radii=None):
-    '''
+    """
     Generates a bodyfixed footprint from a csmapi generated camera model
+    
     Parameters
     ----------
     camera : object
@@ -479,7 +483,7 @@ def generate_bodyfixed_footprint(camera, boundary, radii=None):
     -------
     : object
       ogr polygon
-    '''
+    """
     if radii is None:
         semi_major, semi_minor = get_radii(camera)
     else: