autogen api docs for existing authenticators

local mediawiki doesn't exist!

.gitignore

@@ -51,6 +51,8 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/source/api/gen
+docs/source/api/index.rst
 
 # PyBuilder
 target/
@@ -65,4 +67,4 @@ jupyterhub.sqlite
 jupyterhub_cookie_secret
 
 .vscode/
-.idea/
+.idea/

docs/source/api/authenticator.rst.tpl

@@ -0,0 +1,12 @@
+{{ module }}
+{{ module | length * '=' }}
+
+.. automodule:: {{ module }}
+
+{% for cls in classes %}
+.. autoclass:: {{ cls }}
+{% endfor -%}
+
+{%- for cls in configurables %}
+.. autoconfigurable:: {{ cls }}
+{% endfor %}

docs/source/api/index.rst.tpl

@@ -0,0 +1,10 @@
+OAuthenticators
+===============
+
+.. autosummary::
+   :toctree: gen
+
+   {% for module in modules -%}
+   {{ module }}
+   {% endfor %}
+

docs/source/conf.py

@@ -23,6 +23,81 @@
 copyright = 'Jupyter Contributors'
 author = 'Jupyter Contributors'
 
+import oauthenticator
+
+# The short X.Y version.
+version = '%i.%i' % oauthenticator.version_info[:2]
+# The full version, including alpha/beta/rc tags.
+release = oauthenticator.__version__
+
+
+# -- generate autodoc classes from entrypoints
+
+from collections import defaultdict
+
+import entrypoints
+import jinja2
+
+
+def render_autodoc_modules():
+    authenticator_entrypoints = entrypoints.get_group_named(
+        "jupyterhub.authenticators"
+    ).values()
+
+    api = os.path.join(source, "api")
+    api_gen = os.path.join(api, "gen")
+
+    # modules is a dict of dicts of lists
+    # { '$module': { 'classes': [...], 'configurables': [...] } }
+
+    modules = defaultdict(lambda : defaultdict(list))
+
+    # pre-load base classes
+    modules['oauthenticator.oauth2'] = {
+        'classes': [
+            'OAuthLoginHandler',
+            'OAuthCallbackHandler',
+        ],
+        'configurables': [
+            'OAuthenticator',
+        ],
+    }
+
+    # load Authenticator classes from entrypoints
+    for ep in authenticator_entrypoints:
+        if ep.module_name and ep.module_name.startswith('oauthenticator.'):
+            modules[ep.module_name]['configurables'].append(ep.object_name)
+
+    with open(os.path.join(api, "authenticator.rst.tpl")) as f:
+        tpl = jinja2.Template(f.read())
+
+    try:
+        os.makedirs(os.path.join(api_gen))
+    except FileExistsError:
+        pass
+
+    for mod, mod_content in modules.items():
+        dest = os.path.join(api_gen, mod + ".rst")
+        print(
+            "Autogenerating module documentation in {} with classes: {}".format(
+                dest, mod_content
+            )
+        )
+
+        with open(dest, "w") as f:
+            f.write(tpl.render(module=mod, **mod_content))
+
+    # render the module index
+    with open(os.path.join(api, "index.rst.tpl")) as f:
+        index_tpl = jinja2.Template(f.read())
+
+    with open(os.path.join(api, "index.rst"), "w") as f:
+        f.write(index_tpl.render(modules=modules))
+
+
+render_autodoc_modules()
+
+autodoc_mock_imports = ["tornado", "jwt", "mwoauth", "globus_sdk"]
 
 # -- General configuration ---------------------------------------------------
 
@@ -31,6 +106,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
     'autodoc_traits',
@@ -48,16 +124,16 @@
 
 import recommonmark
 from recommonmark.transform import AutoStructify
+from recommonmark.parser import CommonMarkParser
 
 
 def setup(app):
     app.add_config_value('recommonmark_config', {'enable_eval_rst': True}, True)
     app.add_stylesheet('custom.css')
     app.add_transform(AutoStructify)
+    app.add_source_parser(CommonMarkParser)
 
 
-source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
-
 source_suffix = ['.rst', '.md']
 
 # -- Options for HTML output -------------------------------------------------

setup.py

@@ -80,7 +80,6 @@ def run(self):
             'local-google = oauthenticator.google:LocalGoogleOAuthenticator',
 
             'mediawiki = oauthenticator.mediawiki:MWOAuthenticator',
-            'local-mediawiki = oauthenticator.mediawiki:LocalMWOAuthenticator',
 
             'okpy = oauthenticator.okpy:OkpyOAuthenticator',
             'local-okpy = oauthenticator.okpy:LocalOkpyOAuthenticator',