Generate reference using sphinx-autoapi

sphinx-autoapi automatically generates a complete reference
by *statically* parsing the source files in our code. This is a new,
straightforward way to interact with existing and new documentation
otherwise only accessible through docstrings.

This does not propogate to any other pages in the documentation not
generated at the top-level (e.g., the astrodata/recipe manuals). But
these are still included in the reference API regardless.

This also allows smart linking to the API reference from within
docstrings. e.g., if one wants to reference the AstroData class,
you can just do the following:
    :py:class:`~astrodata.core.AstroData`

This creates a link to the reference entry for AstroData's class. If
desired it could be included using a replacement directive
    .. |AstroData| replace:: :py:class:`~astrodata.core.AstroData`

There are other options/configurations to streamline this a bit. This
commit also build fine, but there are some circular references and
duplicate object references that need to be either resolved or better
handled.

Obviously, there is no good way to implement this other than finding
references in the docstrings and changing them "manually" if they
don't properly link to the right place. I'm writing a script for the
astrodata package to maintain a list of these kinds of broken links
that could probably be applied to this. But, no ETC on that.

doc/DRAGONS/conf.py

@@ -33,9 +33,15 @@
     'sphinx.ext.imgmath',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary',
+    # 'sphinx.ext.inheritance_diagram',
+    'autoapi.extension'
     #    'sphinx.ext.githubpages',
 ]
 
+# Turn on autosummary
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -79,7 +85,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '*test*/', '*/generated/']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -112,11 +118,12 @@
 #html_theme = 'alabaster'
 html_theme = 'sphinx_rtd_theme'
 
-
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'logo_url' : 'https://dragons.readthedocs.io/',
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -187,7 +194,6 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'DRAGONS'
 
-
 # -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
@@ -209,8 +215,8 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'DRAGONS.tex', 'DRAGONS',
-   'Gemini Observatory', 'manual'),
+    ('index', 'DRAGONS.tex', 'DRAGONS',
+     'Gemini Observatory', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -232,8 +238,6 @@
 
 # If false, no module index is generated.
 #latex_domain_indices = True
-
-
 # -- Options for manual page output --------------------------------------------
 
 # One entry per manual page. List of tuples
@@ -245,17 +249,15 @@
 
 # If true, show URL addresses after external links.
 #man_show_urls = False
-
-
-# -- Options for Texinfo output ------------------------------------------------
+    # -- Options for Texinfo output ------------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'DRAGONS', 'DRAGONS',
-   'Gemini Observatory', 'DRAGONS', 'One line description of project.',
-   'Miscellaneous'),
+    ('index', 'DRAGONS', 'DRAGONS',
+    'Gemini Observatory', 'DRAGONS', 'One line description of project.',
+    'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -266,29 +268,24 @@
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
+    # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'http://docs.python.org/': None}
 
 # Activate the todos
 todo_include_todos = True
 
 # Adding style in order to have the todos show up in a red box.
-
-
 def setup(app):
-   app.add_css_file('todo-styles.css')
-   app.add_css_file('rtd_theme_overrides.css')
-   app.add_css_file('css/rtd_theme_overrides_references.css')
-   app.add_css_file('fonts.css')
-
+    app.add_css_file('todo-styles.css')
+    app.add_css_file('rtd_theme_overrides.css')
+    app.add_css_file('css/rtd_theme_overrides_references.css')
+    app.add_css_file('fonts.css')
 
 rst_epilog = """
 .. role:: raw-html(raw)
-   :format: html
+    :format: html
 
-.. |GMOSImgTut| replace:: :raw-html:`<a href="http://GMOSImg-DRTutorial.readthedocs.io/en/{v}">GMOS Imaging Data Reduction Tutorial</a>`
+.. |GMOSImgTut| replace:: :raw-html:`<a href="./projects/gmosimg-drtutorial/{v}">GMOS Imaging Data Reduction Tutorial</a>`
 .. |NIRIImgTut| replace:: :raw-html:`<a href="http://NIRIImg-DRTutorial.readthedocs.io/en/{v}">NIRI Imaging Data Reduction Tutorial</a>`
 .. |F2ImgTut| replace:: :raw-html:`<a href="http://F2Img-DRTutorial.readthedocs.io/en/{v}">Flamingos-2 Imaging Data Reduction Tutorial</a>`
 .. |GSAOIImgTut| replace:: :raw-html:`<a href="http://GSAOIImg-DRTutorial.readthedocs.io/en/{v}">GSAOI Imaging Data Reduction Tutorial</a>`
@@ -309,3 +306,29 @@ def setup(app):
 .. |RSUserShow|  replace:: http://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/
 
 """.format(v = rtdurl)
+
+# autoapi
+autoapi_dirs = [
+    '../../astrodata/',
+    '../../gemini_instruments/',
+    '../../geminidr/',
+    '../../gempy/',
+    '../../recipe_system/'
+]
+
+autoapi_ignore = [
+    '*test*',
+    '*/doc/*',
+    '*conf.py',
+    '*sscripts/*'
+]
+
+autoapi_options = [
+    'members',
+    'undoc-members',
+    'show-inheritance',
+    # 'show-module-summary',
+    # 'show-inheritance-diagram',
+]
+
+autoapi_member_order = 'groupwise'