Merge 7280f10 into 9010f4a

georgia-tech-db · Oct 27, 2020 · fd04cf6 · fd04cf6
2 parents 9010f4a + 7280f10
commit fd04cf6
Show file tree

Hide file tree

Showing 32 changed files with 210 additions and 190 deletions.
diff --git a/.gitignore b/.gitignore
@@ -146,3 +146,5 @@ evaql_parserVisitor.py
 
 #VSCode
 .vscode/*
+
+/api-docs/_autosummary/
diff --git a/api-docs/_templates/custom-class-template.rst b/api-docs/_templates/custom-class-template.rst
@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/api-docs/_templates/custom-module-template.rst b/api-docs/_templates/custom-module-template.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/api-docs/conf.py b/api-docs/conf.py
@@ -10,14 +10,19 @@
 # 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 warnings
 import os
 import sys
 
-sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath('..'))
-sys.path.insert(0, os.path.abspath('../src/'))
+sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath('../'))
+
+
+# Temp. workaround for
+# https://github.com/agronholm/sphinx-autodoc-typehints/issues/133
+warnings.filterwarnings(
+    'ignore', message='sphinx.util.inspect.Signature\(\) is deprecated')
 
-import sphinx_rtd_theme
 
 # -- Project information -----------------------------------------------------
 
@@ -30,7 +35,7 @@
 
 master_doc = 'index'
 
-html_theme = 'mps'
+# html_theme = 'mps'
 html_sidebars = {
     '**': ['localtoc.html', 'relations.html', 'links.html', 'contact.html'],
 }
@@ -41,10 +46,24 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx',
-    'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon', 'sphinx.ext.graphviz', 'extensions.mps'
+    'sphinx.ext.autosummary',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.graphviz',
+    'extensions.mps'
 ]
+autosummary_generate = True  # Turn on sphinx.ext.autosummary
+autoclass_content = "both"  # Add __init__ doc (ie. params) to class summaries
+# Remove 'view source code' from top of page (for html, not python)
+html_show_sourcelink = False
+# If no class summary, inherit base class summary
+autodoc_inherit_docstrings = False
+numpydoc_show_class_members = False
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -65,12 +84,11 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-# MOCK_MODULES = ['numpy', 'sqlalchemy', 'petastorm', 'sqlalchemy.orm']
-# for mod_name in MOCK_MODULES:
-#     sys.modules[mod_name] = mock.Mock()
-
 autodoc_mock_imports = ["numpy", "sqlalchemy", "sqlalchemy_utils",
-                        "petastorm", "yaml", "pyspark"]
+                        "sqlalchemy.orm", "sqlalchemy.orm.exc",
+                        "sqlalchemy.types",
+                        "petastorm", "yaml", "pyspark", "torch",
+                        "pandas", "cv2"]
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -79,9 +97,26 @@
 # html_theme = 'sphinx_rtd_theme'
 
 # html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-html_theme_path = ['themes']
+# html_theme_path = ['themes']
+
+
+# on_rtd is whether on readthedocs.org,
+# this line of code grabbed from docs.readthedocs.org...
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # 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".
 # html_static_path = ['_static']
+
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    return False
+
+
+def setup(app):
+    app.connect('autodoc-skip-member', autodoc_skip_member)
diff --git a/api-docs/documentation/catalog/catalog.models.rst b/api-docs/documentation/catalog/catalog.models.rst
diff --git a/api-docs/documentation/catalog/catalog.rst b/api-docs/documentation/catalog/catalog.rst
diff --git a/api-docs/documentation/catalog/catalog.services.rst b/api-docs/documentation/catalog/catalog.services.rst
diff --git a/api-docs/documentation/executor.rst b/api-docs/documentation/executor.rst
diff --git a/api-docs/documentation/index.rst b/api-docs/documentation/index.rst
diff --git a/api-docs/guide/index.rst b/api-docs/guide/index.rst
@@ -4,9 +4,7 @@ Guide
 *****
 
 .. toctree::
-    :numbered:
-
     overview
     setup
     contributing
-    license
+    license